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.
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:
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.
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.
A integração é compatível com os seguintes sistemas operacionais:
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.
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.
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.
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`.
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.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
'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.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.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
.
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:
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.
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:
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.
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:
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.
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
.
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)
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.
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
.
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.
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']
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.
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.
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()
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.