zsynctech-studio-sdk 1.1.5

Execution monitoring SDK

ZSyncTech Studio SDK

SDK Python para monitoramento de execuções com integração à plataforma ZSyncTech.

O que é o ZSyncTech Studio SDK?

O ZSyncTech Studio SDK é uma biblioteca Python desenvolvida para facilitar a criação de robôs de automação que se integram perfeitamente com a plataforma ZSyncTech. Ele fornece uma estrutura padronizada para organizar seu código em execuções, tarefas e passos, permitindo monitoramento em tempo real, tratamento de erros e rastreabilidade completa de cada operação.

Com o SDK, você pode transformar qualquer script Python em um robô de automação profissional, com logs estruturados, métricas de desempenho e integração com a plataforma de gerenciamento.

Funcionalidades Principais

Decorators Intuitivos

Use @execution, @task e @step para estruturar seu código de forma clara e organizada. Cada decorator adiciona automaticamente monitoramento, logging e integração com a plataforma sem necessidade de código adicional.

Monitoramento em Tempo Real

Acompanhe o progresso das suas execuções diretamente na plataforma ZSyncTech. Veja em tempo real quantas tarefas foram processadas, quais estão em andamento e identifique rapidamente problemas quando ocorrem.

Tratamento Inteligente de Exceções

Mapeie exceções específicas para status personalizados da plataforma. Por exemplo, configure para que uma exceção OutOfHoursError finalize a execução com status OUT_OF_OPERATING_HOURS ao invés de um erro genérico.

Sistema de Observers

Receba notificações de eventos durante a execução através de observers customizáveis. Ideal para integração com sistemas de alerta, logging personalizado ou qualquer ação que precise ser executada em resposta a eventos específicos.

Deploy Simplificado

Transforme seu robô em um serviço que aguarda comandos da plataforma com apenas uma chamada de método. O SDK gerencia toda a comunicação HTTP, autenticação e sincronização de status automaticamente.

Instalação

pip install zsynctech-studio-sdk

Ou usando uv:

uv add zsynctech-studio-sdk

Exemplo Rápido

from zsynctech_studio_sdk import execution, task, step, set_total_tasks

@step(code="0001")
def processar_dados():
    # Sua lógica aqui
    pass

@task
def minha_tarefa():
    processar_dados()

@execution
def minha_execucao():
    set_total_tasks(10)

    for i in range(10):
        minha_tarefa()

if __name__ == "__main__":
    minha_execucao()

Deploy para Plataforma

Para integrar com a plataforma ZSyncTech:

from zsynctech_studio_sdk import execution, task, step, set_total_tasks, ExecutionStatus

class OutOfHoursError(Exception):
    pass

@step(code="STEP-001")
def passo_um():
    print("Executando passo 1")

@task
def processar_item():
    passo_um()

@execution(
    exception_handlers={
        KeyboardInterrupt: ExecutionStatus.INTERRUPTED,
        OutOfHoursError: ExecutionStatus.OUT_OF_OPERATING_HOURS
    }
)
def meu_robo():
    set_total_tasks(10)

    for _ in range(10):
        processar_item()

if __name__ == "__main__":
    meu_robo.deploy(
        instance_id="seu-instance-id",
        secret_key="sua-secret-key",
        server="https://api.zsynctech.com",
        port=8080
    )

Estrutura Hierárquica

O SDK segue uma hierarquia de três níveis que reflete a estrutura típica de um processo de automação:

Execution
├── Task 1
│   ├── Step 1
│   ├── Step 2
│   └── Step 3
├── Task 2
│   ├── Step 1
│   └── Step 2
└── Task 3
    └── Step 1

Execution (Execução)

Representa uma execução completa do robô. É o nível mais alto da hierarquia e engloba todo o processamento. Uma execução pode conter múltiplas tasks e mantém métricas gerais como total de tarefas, tarefas concluídas e tempo de execução.

Exemplo: "Processamento diário de notas fiscais"

Task (Tarefa)

Representa uma unidade de trabalho dentro da execução. Geralmente corresponde ao processamento de um item individual. Tasks podem ser configuradas com retry automático e mantêm métricas dos steps executados.

Exemplo: "Processar nota fiscal #12345"

Step (Passo)

Representa uma ação atômica dentro de uma task. É o nível mais granular e permite rastreamento detalhado de cada operação realizada. Steps são úteis para identificar exatamente onde um erro ocorreu.

Exemplo: "Preencher campo CNPJ", "Clicar no botão Salvar"