Proton Cloud SDK

La Proton Cloud SDK es la dependencia que el código de una automatización usa para comunicarse con Proton durante la ejecución. Con ella, la automatización:

• descubre qué componente se ejecuta ahora y abre y cierra cada paso;
• lee los parámetros del dataset y las variables del ambiente de la ejecución;
• registra los parámetros de salida, el log, el error y las evidencias;
• marca el resultado de la ejecución.

La SDK hace las llamadas a la API de ejecución por ti. Usa la referencia de la API para entender lo que pasa por debajo o para integrar un lenguaje que todavía no tiene SDK.

Lenguajes

Lenguaje	Paquete	Versión	Dónde
Python 3.10+	protoncloud-sdk	5.5.0	PyPI
Java 21+	br.com.protoncloud:protoncloud-sdk	5.5.0	Repositorio Maven público https://maven.protoncloud.com.br

Las dos siguen la misma numeración. La versión 5.x se comunica con Proton 5.

Python

pip install protoncloud-sdk

Java

<repositories>
    <repository>
        <id>protoncloud</id>
        <url>https://maven.protoncloud.com.br</url>
    </repository>
</repositories>

<dependency>
    <groupId>br.com.protoncloud</groupId>
    <artifactId>protoncloud-sdk</artifactId>
    <version>5.5.0</version>
</dependency>

Los detalles de cada lenguaje están en Python y Java.

Ejecutor de componentes

A partir de la 5.3, la SDK trae el bucle que ejecuta los pasos del dataset, que antes cada proyecto copiaba en su punto de entrada. El proyecto indica, por el nombre del componente, qué código ejecutar, y el ejecutor se encarga del resto:

• registra Running cuando el primer paso está por ejecutarse;
• en cada paso, abre el paso, llama al componente solo con sus parámetros, registra las salidas que este devuelve, sube las evidencias nuevas de la carpeta evidencias/ y cierra el paso;
• al final, registra Passed; cuando un paso falla, registra el stack trace en el panel de error y Failed con el motivo de la falla (negocio, técnico o ambiente), y el paso queda en Failed.

Desde la 5.5.0, el ejecutor también cierra la sesión después del último paso (close_at_end en Python, closeAtEnd en Java), para que el video de una ejecución que pasó llegue a Proton, y la falla que ocurre antes del primer paso llega a Proton por record_failure (Python) o recordFailure (Java). Consulta los ejemplos en Python y Java.

El código de negocio no importa la SDK y se ejecuta igual fuera de Proton. Un proyecto puede encargarse de varias plataformas (SAP, web, API, desktop), cada una un sistema en Proton vinculado al mismo repositorio: el ejecutor sigue en el mismo proceso mientras el proyecto tenga el componente del siguiente paso.

Los proyectos modelo muestran la estructura completa, en Python y en Java.

Cómo encuentra la SDK a Proton

El Proton Runner descarga el código del repositorio e inicia la automatización con la dirección de la API (PROTON_HOST) y el id de la ejecución. La SDK lee los dos por su cuenta: el mismo proyecto reporta al servidor donde nació la ejecución, sin editar ningún archivo.

Token de la ejecución

El runner actualizado le pide a Proton, para cada ejecución, un token de la ejecución y se lo entrega a la automatización en PROTON_TOKEN. Este token:

• vale solo para esa ejecución: abrir y cerrar los pasos, leer los parámetros y el ambiente, registrar las salidas, el log y las evidencias, y leer el dataset y el grupo de la propia ejecución;
• vale solo mientras la ejecución está en curso, y como máximo 24 horas;
• nunca se guarda en el proyecto ni en el disco del runner.

A partir de la 5.2.0, la SDK usa el token de la ejecución aunque el proyecto tenga otro en el archivo de configuración. Con él, el proyecto no necesita guardar ningún token.

Con un runner anterior, la SDK lee el token de la variable PROTON_TOKEN de la máquina del runner o del archivo de configuración del proyecto (proton.ini en Python, config.properties en Java), como antes. El token se crea en Mi Perfil, en Proton, o lo crea el administrador para un usuario robot. Nunca guardes el token en el repositorio.

Fuera de una ejecución de Proton, sin el id de la ejecución, la SDK no llama al servidor: la misma prueba se ejecuta en la máquina de quien desarrolla.

Si vienes de Proton Lib

La Proton Cloud SDK es la antigua Proton Lib con otro nombre. El código sigue igual:

• Python: el paquete protoncloud-sdk mantiene el import proton (from proton.proton_automation import ...). Si el proyecto tenía una copia de la carpeta proton/, bórrala después de instalar el paquete: la copia local tiene precedencia sobre el paquete instalado.
• Java: la dependencia br.com.atomicsolutions.proton:proton-lib pasa a ser br.com.protoncloud:protoncloud-sdk. Los paquetes Java siguen siendo br.com.atomicsolutions.*, así que ningún import cambia.

Lo que cambió de comportamiento en Proton 5 está en Versiones.