Guia - Primeiros Passos

Conteúdo

INTRODUÇÃO

Neste guia, será apresentado uma sequência de dicas e exemplos úteis sobre como utilizar nossa plataforma portal SRS Cloud, e sobre como configurar a integração de seus processos juntamente, utilizando a nossa biblioteca disponível, o SRSCloud_Integration. O exemplo abordado a seguir se trata de um processo de consulta de dólar.

Visite também nossa página de ajuda, caso queira obter mais detalhes do funcionamento de cada página e estrutura de nosso portal bem como o cadastro para acesso à plataforma.

Pré-requisitos

Para garantir a integração bem-sucedida e a utilização eficaz do BotAgent com o portal SRS Cloud, é fundamental assegurar que todos os pré-requisitos sejam atendidos. A seguir, estão listados os requisitos essenciais:

Instalação do BotAgent

O BotAgent é um software necessário para a comunicação e execução das tarefas automatizadas. Ele deve ser instalado no sistema onde a integração será realizada e deve estar conectado(on-line). O arquivo pode ser baixado na página de Downloads.

INFO: É fundamental inserir o token da máquina do usuário registrada no portal SRS Cloud.

Cadastro de Usuário no Portal SRS Cloud

O portal SRS Cloud é a plataforma onde serão gerenciadas as tarefas e integrações. Para acessar e utilizar suas funcionalidades, é necessário ter um usuário cadastrado.

Para mais informações de cadastro e de acesso, acesse a página Ajuda.

Sistema Operacional

A integração é compatível com os seguintes sistemas operacionais:

  • Windows 10
  • Windows 11
  • Windows Server
Arquivo SRSCloud_Integration.py

Biblioteca em Python com as principais funções necessárias para estabelecer a integração via API com o portal SRS Cloud.

O arquivo pode ser baixado na página de Downloads.

Arquivo srs.json

Arquivo JSON com as configurações e credenciais necessárias para a comunicação e uso da biblioteca SRSCloud_Integration.py.

O arquivo pode ser baixado na página de Downloads.

Criando o Primeiro Projeto/Bot

Este tutorial guiará você passo a passo na criação de uma automação Python simplificada para consultar o valor do dólar em datas específicas. O objetivo deste guia é proporcionar um primeiro contato e um melhor entendimento do gerenciamento eficiente de robôs, filas e execuções, utilizando a biblioteca SRSCloud_Integration e o portal SRS Cloud.

Explorando a Estrutura do Projeto

Primeiramente, será necessário criar uma pasta para armazenar todos os arquivos do projeto. Neste guia, usaremos o nome ConsultaDolar, mas você pode escolher o nome que preferir. Dentro da pasta do projeto ConsultaDolar, a estrutura deve ser a seguinte:

				
					ConsultaDolar
├── bot_consultaDolar.py     <- Arquivo principal será desenvolvido o robô.
├── SRSCloud_Integration.py  <- Biblioteca contendo as funções necessárias para integrar com o portal SRSCloud.
└── srs.json                 <- Arquivo de configuração contendo as credenciais e outras configurações necessárias para o uso de `SRSCloud_Integration.py`.
				
			
Importando Bibliotecas e Recursos

Para utilizar todos os recursos e bibliotecas necessários para o funcionamento do projeto, será necessário fazer algumas importações no código:

				
					import SRSCloud_Integration as srsc
import requests
from datetime import datetime
import sys
import json
				
			
  • SRSCloud_Integration: Biblioteca que contém funções específicas para integrar com o sistema SRS Cloud.
  • requests: Esta biblioteca permite fazer requisições HTTP de maneira simples e eficiente. Ela será utilizada para consultar a API AwesomeAPI e obter o valor do dólar. Além do import no projeto, é necessário fazer sua instalação, através do seguinte comando:
				
					>> pip install requests
				
			
  • datetime: Esta biblioteca fornece classes para manipulação de datas e horários. 
  • sys: Usaremos sys para obter argumentos da linha de comando.
  • json: Esta biblioteca permite a manipulação de dados no formato JSON.
Criando Função para Consultar o Valor do Dólar

Continuando com o desenvolvimento do projeto, vamos criar uma função em Python que consulta o valor do dólar em uma data específica usando a API chamada AwesomeAPI. Vamos entender passo a passo como a função ‘consultar_dolar' é construída e como ela funciona:

				
					# Função para consultar o valor do dólar em uma data específica
def consultar_dolar(data_consulta):

    data = data_consulta.strftime('%Y%m%d')

    # A URL da API com o endpoint para histórico de câmbio do dólar
    api = f'https://economia.awesomeapi.com.br/json/daily/USD-BRL/?start_date={data}&end_date={data}'
    response = requests.get(api)
    
    # verifica se a requisicao foi bem sucedida
    if response.status_code == 200:
        data = response.json()

        # verifica se há dados na resposta JSON
        if data:
            # A API retorna uma lista de registros, pegamos o valor de compra "bid"
            valor_dolar = data[0]['bid']
            return {'Data':data_consulta.strftime('%d/%m/%Y'), 'Valor':float(valor_dolar)}
        else:
            return None
    else:
        print(f"Erro na consulta: {response.status_code}")
        return None
				
			
  • A função 'consultar_dolar' é definida, e ela recebe um parâmetro 'data_consulta', que é a data para a qual queremos consultar o valor do dólar. Através desse parâmetro, a URL da API é construída com a data formatada, especificando o intervalo de datas desejado para a consulta.
  • Uma requisição GET é enviada para a API utilizando a biblioteca requests. O status da requisição é verificado, e, se a requisição for bem-sucedida (status code 200) e houver dados, o conteúdo da resposta JSON é armazenado na variável 'data'. Em seguida, é retornado um dicionário com a data formatada e a cotação do dólar.

Cadastros Portal SRS Cloud

Para que o nosso projeto de consulta do dólar opere de forma automatizada, é crucial realizar alguns cadastros essenciais no portal SRS Cloud, também necessários para a configuração do arquivo srs.json  e integração com o SRSCloud_Integration.

Cadastro Workflow

O fluxo de trabalho do Workflow possui uma sequência pré-definida e coordenada de atividades, que são executadas de forma organizada para alcançar um objetivo específico. Nesta etapa, será registrado o Workflow “Consulta Dolar” com as seguintes informações:

  • Nome: Consulta Dolar
  • Alias: cd
  • Cor (Opcional)
  • Ativo: ativada
  • Expurgo: 15 dias
  • Ignorar timeout (Opcional)
  • Timeout: 5 minutos
  • Descrição (Opcional)

Os nomes das informações podem variar, os exemplos acima são apenas ilustrativos. Para mais detalhes sobre o cadastro de Workflow, consulte a página de Ajuda.

Cadastro Tarefa

As tarefas são atividades específicas que constituem um Workflow. O próximo passo é registrar uma tarefa para a atividade de consultar o valor do dólar através do nosso projeto. A tarefa incluirá as seguintes informações:

  • Nome*: Consulta Valor Dolar
  • Alias*: ct-dolar
  • Cor (Opcional)
  • Ativo: ativada
  • Plataforma: Script Python
  • Máquina: Máquina_tester
  • Execução: Máquina definida
  • Chamada do programa local: C:\ConsultaDolar\bot_consultaDolar.py
  • Tratamento de erro: Retorna item para a fila
  • Interação com Tela: Não
  • SLA: 5 minutos
  • FTE: 5 minutos
  • Descrição (Opcional)

Os nomes das informações podem variar, os exemplos acima são apenas ilustrativos. Para mais detalhes sobre o cadastro de tarefa, consulte a página de Ajuda.

Criando Parâmetro de Entrada

Para permitir a consulta do valor do dólar em uma data específica, é necessário criar um parâmetro de entrada para que a tarefa receba a data. As informações do parâmetro de entrada são as seguintes:

  • Nome: Data
  • Tipo Parâmetro: Entrada
  • Tipo Valor: Texto
  • Obrigatório: Ativado

O nome do parâmetro pode variar, o exemplo acima é apenas ilustrativo. Para mais detalhes sobre o cadastro de parâmetros, consulte a página de Ajuda.

Ao concluir esta etapa de cadastros, temos definidos tanto o Workflow quanto a tarefa associada, incluindo o parâmetro de entrada para a data da consulta.

Configurações SRSCloud_Integration.py e srs.json

Antes de prosseguir com a implementação utilizando o SRSCloud_Integration, é essencial entender e configurar adequadamente o ambiente de integração. Neste tópico, exploraremos as configurações necessárias para utilizar a biblioteca SRSCloud_Integration em conjunto com o arquivo de configuração srs.json.

Configurando SRSCloud_Integration.py

No interior da biblioteca SRSCloud_Integration.py, há uma seção específica para vincular o arquivo srs.json, onde os parâmetros de acesso devem ser definidos. Por meio dessa vinculação, a biblioteca tem acesso às informações necessárias para se autenticar no SRS Cloud e interagir com seus recursos de forma segura e controlada.

				
					with open(f"C:\\ConsultaDolar\\srs.json") as json_data_file:
     config_json = json.load(json_data_file)
				
			
Configurando srs.json

O arquivo srs.json contém alguns parâmetros de configuração necessários para autenticar o acesso ao SRS Cloud e especificar detalhes sobre o workflow, tarefa e máquina associados. 

				
					{
  "srscloud_config": {
    "url": "https://c01.api.srscloud.com.br/api/",
    "token":"Token do usuário",
    "workflowAlias": "cd",
    "tarefaAlias": "ct-dolar", 
    "maquina": "Maquina_tester"
  }
}
				
			

INFO: O parâmetro token nessa configuração refere-se ao token de usuário encontrado em Meu Perfil no portal SRS Cloud.

Integração SRSCloud_Integration

Seguindo o desenvolvimento do projeto, vamos explorar detalhadamente como a função main() coordena o processamento dos itens na fila, utilizando os recursos fornecidos pela biblioteca SRSCloud_Integration.

Obtenção do ID da Fila e Verificação dos Argumentos de Linha de Comando

Ao executar a tarefa pelo Portal SRS Cloud, o BotAgent envia argumentos necessários para a execução do robô desenvolvido, que são acessados através de "sys.argv". A estrutura condicional abaixo é responsável por verificar se há mais de um argumento passado:

				
					

def main():
    # recebe execuções manuais e agendadas
    # recebe o ID da fila em caso de execução manual
    # Observação: ID da execucao -> sys.argv[1] | ID da fila -> sys.argv[2]
        if len(sys.argv) > 1:
           filaId = sys.argv[2] # recebe o ID da fila em caso de execução manual
        else:
           filaId = None # em caso de execução agendada, não há ID da fila
				
			

Se a condição for verdadeira (ou seja, 'len(sys.argv) > 1)', o script entende que está sendo executado manualmente. Nesse caso, o valor da posição 2 do argumento (sys.argv[2]) é atribuído à variável 'filaId'. Este argumento é presumivelmente o ID da fila fornecido manualmente durante a execução do script.

Caso contrário, se a condição for falsa, significa que não há argumentos adicionais além do nome do script. Isso caracteriza uma execução agendada, onde 'filaId' é definida como 'None', indicando que não foi passado nenhum ID de fila.

Inicialização da Execução

Antes de efetivamente gerenciar filas e itens, é preciso iniciar a execução do robô por meio da chamada da função 'execucaoIniciar()'. O resultado é então convertido de JSON para um dicionário Python, do qual é extraído o identificador (ID) da execução.

				
					...
# recebe parâmetros de configuração
inicio = json.loads(srsc.execucaoIniciar())
execucaoId = inicio['ExecucaoId']
				
			
Obtenção do Próximo Item da Fila

Após obter o ID da fila, é necessário verificar se esse ID é nulo ou se possui uma identificação. No código abaixo, essa verificação é realizada por meio de uma estrutura condicional.

				
					...
    if filaId != None:
        filaItem = json.loads(srsc.filaProximoNomeada(execucaoId=execucaoId,filaId=filaId))
    else:
        filaItem = json.loads(srsc.filaProximo(execucaoId=execucaoId))
				
			

Se o ID da fila não for None, isso indica que há uma fila específica com uma identificação (ID) definida. Nesse caso, o programa utiliza a função 'filaProximoNomeada()' para obter e armazenar um item específico dessa fila. Esse cenário é comumente usado em execuções manuais, onde o ID da fila é passado explicitamente como argumento na linha de comando, que é o caso do nosso projeto.

Por outro lado, se o ID da fila for 'None', isso significa que não há uma identificação específica de fila, geralmente indicando uma execução agendada. Neste caso, o programa não tem um ID de fila específico para trabalhar e tratará a execução de maneira diferente utilizando a função 'filaProximo()', da qual retorna o próximo item da fila e é possível alterar a quantidade para trazer mais de um.

Essa abordagem permite que o programa trate execuções manuais e agendadas de maneira diferenciada, garantindo flexibilidade no gerenciamento das filas.

Processamento dos Itens da Fila

Depois de identificar que há uma fila específica, é necessário processar todos os seus itens. O código a seguir demonstra como isso é feito:

				
					...
    while filaItem['Autorizado'] == True:
        fila = filaItem['Fila'][0] # Extrai o primeiro item da fila
        filaId = fila['FilaId'] # Obtém o ID da fila do item atual
        parametros = json.loads(fila['ParametrosEntrada'])
        data_parametro = parametros['Data']
				
			

Enquanto há itens na fila, indicado por ‘Autorizado’ ser verdadeiro, o programa pode realizar a execução efetiva do objetivo do projeto, que é a consulta do valor do dólar, sendo essa execução tratada como um item da fila. Em seguida, para cada item na fila, extraímos o primeiro item e obtemos seu ID de fila.

Para realizar a consulta do dólar, é necessário fornecer uma data. Essa data é passada como um parâmetro de entrada ao iniciar a execução da tarefa no portal SRS Cloud. Usamos a informação de 'filaItem' para obter esse parâmetro.

				
					...
    while filaItem['Autorizado'] == True:
        ...
        try:
            data_obj = datetime.strptime(data_parametro, '%d/%m/%Y')
            resultado = consultar_dolar(data_obj)

            if resultado is None:
                resultado = "Valor não encontrado."

            saida = {'Valor Dolar':f'{resultado["Valor"]}'}
            proximo = json.loads(srsc.filaAtualizarProx(execucaoId=execucaoId, filaId=filaId, statusId=2, parametrosSaida=json.dumps(saida)))
            filaItem['Autorizado'] = proximo['Proximo']['Autorizado']

        except (ValueError, OverflowError) as e:
            srsc.execucaoFinalizar(execucaoId=execucaoId, status='erro', mensagem='Execução falhou')
            
    srsc.execucaoFinalizar(execucaoId=execucaoId, status='ok', mensagem='Execução finalizada')
				
			

Com todos os dados necessários, prossegue o processamento do item da fila com o trecho de código 'try-expect', que executa qualquer exceção que ocorrer durante a execução onde será realizado a captura e o tratamento.

Com as informações essenciais extraídas do item da fila, o próximo passo é realizar a consulta do valor do dólar. Nesse processo, a função 'consultar_dolar' é empregada para buscar o valor correspondente à data especificada em 'data_parametro'. Antes da consulta, 'data_parametro' é convertida em um objeto 'datetime' utilizando o formato que representa “dia/mês/ano”. Se o resultado da consulta for 'None', significa que o valor do dólar não foi encontrado para a data especificada.

Após obter o resultado da consulta do valor do dólar, é preparada a saída no formato desejado, neste caso, um dicionário com a chave 'Valor Dolar' contendo o valor obtido.

Para concluir o processamento do item da fila, é feita a chamada da função 'filaAtualizarProx()' para atualizar o status do item atual na fila, além de retornar o próximo item, se existir. Os parâmetros passados para esta função incluem:

  • 'execucaoId' para identificar a execução atual;
  • 'filaId' para identificar a fila específica;
  • 'saida' convertida para JSON.

Após a atualização, o código define a autorização do próximo item da fila (‘Autorizado’) com base na resposta retornada pela função 'filaAtualizarProx()'.

No tratamento de excessões, se o programa encontrar erro, a função srsc.execucaoFinalizar() finaliza a execução atual com status de erro e uma mensagem indicando que a execução falhou. Isso garante que a execução seja encerrada corretamente e registra o problema para futuras investigações.

Por fim, após todos os itens da fila serem devidamente processados, a função execucaoFinalizar() é chamada para finalizar a execução, registrando o status como “ok” para a execução concluída com sucesso.

Finalização

Ao seguir todos os passos, o projeto final ficará como o código abaixo:

				
					# Biblioteca que contém funções específicas para integrar com o sistema SRS Cloud.
import SRSCloud_Integration as srsc
import requests
from datetime import datetime
import sys
import json

def consultar_dolar(data_consulta):

    data = data_consulta.strftime('%Y%m%d')
    api = f'https://economia.awesomeapi.com.br/json/daily/USD-BRL/?start_date={data}&end_date={data}'
    response = requests.get(api)
    
    if response.status_code == 200:
        data = response.json()
        if data:
            valor_dolar = data[0]['bid']
            return {'Data':data_consulta.strftime('%d/%m/%Y'), 'Valor':float(valor_dolar)}
        else:
            return None
    else:
        print(f"Erro na consulta: {response.status_code}")
        return None

def main():
    if len(sys.argv) > 1:
        filaId = sys.argv[2]
    else:
        filaId = None
    
    inicio = json.loads(srsc.execucaoIniciar())
    execucaoId = inicio['ExecucaoId']

    if filaId != None:
        filaItem = json.loads(srsc.filaProximoNomeada(execucaoId=execucaoId,filaId=filaId))
    else:
        filaItem = json.loads(srsc.filaProximo(execucaoId=execucaoId))
    
    while filaItem['Autorizado'] == True:
        fila = filaItem['Fila'][0]
        filaId = fila['FilaId']
        parametros = json.loads(fila['ParametrosEntrada'])
        data_parametro = parametros['Data']
        
        try:
            data_obj = datetime.strptime(data_parametro, '%d/%m/%Y')
            resultado = consultar_dolar(data_obj)

            if resultado is None:
                resultado = "Valor não encontrado."

            saida = {'Valor Dolar':f'{resultado["Valor"]}'}
            proximo = json.loads(srsc.filaAtualizarProx(execucaoId=execucaoId, filaId=filaId, statusId=2, parametrosSaida=json.dumps(saida)))
            filaItem['Autorizado'] = proximo['Proximo']['Autorizado']

        except (ValueError, OverflowError) as e:
            srsc.execucaoFinalizar(execucaoId=execucaoId, status='erro', mensagem='Execução falhou')

    srsc.execucaoFinalizar(execucaoId=execucaoId, status='ok', mensagem='Execução finalizada')

if __name__ == "__main__":
    main()

				
			

Executando Tarefa no Portal SRS Cloud

Agora para a parte final dessa guia, vamos explorar o passo a passo para executar a tarefa de consultar o valor do dólar no portal SRS Cloud. Este processo ilustra como o SRS facilita a execução de automações, fornecendo uma interface intuitiva para executar, monitorar e analisar o desempenho das tarefas automatizadas.

Depois de acessar o portal SRS Cloud e encontrar a tarefa dentro do workflow correspondente que será executada, você será direcionado para a seguinte tela:

Para iniciar a execução da tarefa, basta acessar a seção de Tarefas e selecionar o botão “Executar” na coluna “Ação” correspondente à tarefa “Consulta Valor Dólar”:

Em seguida, será solicitado que informe a data específica para a consulta do valor do dólar, conforme ilustrado na imagem abaixo:

Após a execução da tarefa, é registrado na seção de Fila, onde você pode ter uma visão geral do status da consulta do dólar e informações sobre como data e hora de inclusão, prioridade e ação de encerrar execução disponível. O registro indica que a tarefa está em andamento e ainda não foi concluída:

A cada item da fila processado, são registradas informações essenciais como o status da fila e os dados processados do item,  acessados na opção detalhes. Durante essa execução, é possível observar que o parâmetro de entrada foi extraído e utilizado, e que o parâmetro de saída com o valor do dólar foi encontrado com sucesso:

Finalmente, é possível revisar o histórico da execução realizada, onde são fornecidas informações sobre se a execução foi concluída com sucesso e seus registros de log associados. Nesse histórico, pode-se confirmar que a tarefa foi encerrada com êxito e gerou os dados esperados.