Scripts Python e HCL no Robôs

O aplicativo Robôs oferece scripts nativos na nuvem que você pode usar para análises de dados ou automação de partes do fluxo de trabalho do Diligent One na sua organização. Os scripts do Robôs combinam os recursos do Python e todas suas bibliotecas de apoio com o HighBond Command Language (HCL), nossa biblioteca Python personalizada para análises de dados voltadas a domínios e automação do Diligent One.

O Robôs continua sendo compatível com análise e automação de dados usando o ACLScript e os scripts carregados do Analytics. Assim, você pode se beneficiar do investimento atual no ACL (Linguagem de comando de Auditoria) e de todas as possibilidades oferecidas pelo Python (uma linguagem de programação padrão do setor) e pelo HCL.

Três tipos de robô

O aplicativo Robôs contém três tipos de robô. Embora sejam semelhantes, os diversos tipos de robôs são usados em diferentes cenários de scripts:

• Robô ACL Permite análise de dados em escala real com scripts carregados do Analytics e tarefas agendadas. Os scripts podem ser executados na nuvem ou no local.

• Robô HighBond Permite análise de dados completa com scripts Python/HCL criados diretamente no robô e tarefas agendadas. Os scripts só podem ser executados na nuvem.

• Robô de fluxo de trabalho É compatível com análise de dados simples ou automação de partes do fluxo de trabalho do Diligent One com scripts Python/HCL criados diretamente no robô, bem como tarefas agendadas ou baseadas em eventos. Os scripts só podem ser executados na nuvem.

  Observação

  Para acessar os robôs de fluxo de trabalho, você deve ter o tipo de usuário Administrador do Sistema com uma assinatura Profissional.

  O intuito é que um Administrador do Sistema com uma assinatura Profissional possa configurar tarefas nos robôs de fluxo de trabalho que são acionados por eventos do Diligent One. Esta funcionalidade ainda está em desenvolvimento e não está disponível no momento.

Comparação de tipos de robôs

Os três tipos de robôs têm finalidades distintas e funcionalidades separadas. Não é possível combinar ACLScript e Python/HCL em um único robô.

Característica do robô	Robô ACL	Robô HighBond	Robô de fluxo de trabalho
Uso pretendido	análise de dados e automação		automação da Plataforma Diligent One
Suporte a linguagens	ACLScript	Python Pandas, NumPy, Requests e outras bibliotecas Python padrão Biblioteca Python personalizada da HCL (HighBond Command Language)
Local de criação de scripts	Analytics	Robôs
Local de execução do script	nuvem local	nuvem
Opções para executar uma tarefa	agendado execução ad-hoc (manual)		acionamento por evento do Diligent One agendado execução ad-hoc (manual)
Tempo máximo de execução da tarefa	agente do Robôs baseado na nuvem: 60 minutos agente do Robôs local: controlado pela rede do cliente	Sem limite Observação Um limite de 12 horas está planejado, mas ainda não foi implementado. Caso precise parar uma tarefa que está em execução há muito tempo, clique em Cancelar execução da tarefa na guia Execuções de tarefas.	15 minutos
Máximo de tarefas executadas simultaneamente	5	5	50
Permissões obrigatórias	ser um colaborador do robô nível de acesso controlado pela função do robô do colaborador (Proprietário, Editor, Revisor)		Tipo de usuário Administrador do Sistema com assinatura Profissional

Editor de script do Robôs

Os robôs HighBond e de fluxo de trabalho contêm um editor de scripts integrado para criar scripts Python/HCL e executá-los de forma interativa (manualmente). O editor de script é modelado com base no aplicativo Jupyter Notebook, um ambiente de desenvolvimento popular na comunidade de ciência de dados. O editor de script usa Criação de scripts com abordagem baseada em células.

Criação de scripts com abordagem baseada em células

O recurso mais óbvio do editor de script é a capacidade de usar várias células para conter os blocos individuais de código que compõem um único script. Se você não está familiarizado como o Jupyter Network, a criação de scripts com abordagem baseada em células pode parecer complicada no início. Na verdade, essa abordagem é fácil de usar e oferece benefícios que você logo reconhecerá.

Principais características da criação de scripts com base em células

• O uso de várias células é opcional Se você não quiser, não precisa usar várias células. É possível criar e executar um script inteiro usando uma única célula.

• Divisões lógicas As células permitem dividir um script em blocos lógicos à sua escolha e executá-los manualmente uma a um, em qualquer ordem, ou como uma sequência completa.

  Por exemplo, esta é uma possível organização básica de um script em quatro células:

  • primeira célula importar bibliotecas do Python

  • segunda célula importar dados

  • terceira célula analisar os dados

  • quarta célula saída dos resultados da análise

• Benefício das células O uso de células no desenvolvimento de scripts oferece estes benefícios:

  • Você pode trabalhar isoladamente em células individuais, testando e aprimorando essas células, ignorando temporariamente a lógica de script das demais células.

  • Depois da execução inicial das células de importação inicial, você não precisa continuar a executá-las enquanto desenvolve e testa várias vezes as células seguintes.

  • Você pode usar células para impor uma ordem visual aos scripts, facilitando a visualização e compreensão da relação entre os diferentes blocos lógicos para você ou outra pessoa.

• Indicador de sequência Ao lado de cada célula, há um indicador numérico que exibe a ordem em que a célula foi executada durante uma sessão de script. Por exemplo: [7].

  Quando você executa uma célula, o indicador é incrementado considerando quaisquer outras células intermediárias executadas. Por exemplo, um indicador pode mudar de [7] para [10] se duas outras células intermediárias foram executadas (ou uma célula intermediária foi executada duas vezes).

• Memória da sessão e valores armazenados Os dataframes e valores de variáveis mantidos na memória durante uma sessão de script são atualizados de acordo com a sequência de execução das células.

  Normalmente, as células são estruturadas para executar sequencialmente de cima para baixo durante uma execução de script agendada sem supervisão. Alguns dataframes ou valores de variáveis podem ser atualizados progressivamente com base na lógica do script. Se você executa manualmente células fora da ordem, o estado atual de um dataframe ou valor de variável pode ser diferente do esperado, o que pode resultar em um erro ou resultado incorreto. Para restaurar o dataframe ou valor de variável para o estado esperado, basta executar novamente todas as células que fazem referência ao dataframe ou variável na ordem pretendida.

• Exibição da saída da célula por padrão, a execução de uma célula exibe somente a saída da última expressão na célula. Se você quiser ver a saída de várias expressões em uma célula, pode colocá-las em células separadas. No entanto, uma abordagem mais conveniente é definir uma opção de configuração no editor de script.

  • Configurar as células para exibir a saída de todas as expressões:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Redefinir as células para exibir somente a saída da última expressão:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Dica

  Você pode usar a definição da configuração para alternar entre os dois modos, conforme a necessidade. Para ver opções de configuração adicionais, consulte a documentação online do Jupyter ou IPython.

Atalhos de teclado no editor de scripts do Robôs

Os atalhos de teclado no editor de scripts oferecem conveniência e velocidade enquanto você desenvolve um script. No editor de scripts, use um destes métodos para ver uma lista de atalhos disponíveis:

• Pressione Ctrl+/

• Clique no ícone Atalho de teclado na barra de título

Os atalhos disponíveis estão listados abaixo.

Atalho de teclado	Ação
Ctrl + Shift + Enter	Executar célula selecionada
Ctrl + Shift + M	Executar todas as células sequencialmente
Ctrl + Shift + Y	Executar a célula selecionada e todas as células acima
Ctrl + Shift + U	Executar a célula selecionada e todas as células abaixo
Ctrl + Shift + I	Parar a execução do script
Ctrl + Shift + K Ctrl + Shift + seta para cima	Selecionar célula acima
Ctrl + Shift + J Ctrl + Shift + seta para baixo	Selecionar célula abaixo
Ctrl + Shift + H Ctrl + Shift + Home	Selecionar primeira célula
Ctrl + Shift + L Ctrl + Shift + End	Selecionar última célula
Ctrl + Shift + A	Adicionar célula acima
Ctrl + Shift + B	Adicionar célula abaixo
Ctrl + Shift + D	Excluir célula selecionada
Ctrl + Shift + Z	Mover célula para cima
Ctrl + Shift + X	Mover célula para baixo

Recursos do Jupyter Notebook não incluídos no editor de script do Robôs

Como mencionado acima, o editor de script do Robôs é modelado com base no aplicativo Jupyter Notebook. Os recursos do Jupyter abaixo não estão incluídos no editor de script, embora alguns deles possam ser incluídos com a evolução futura do produto:

• Operações no nível de célula:

  • desfazer/refazer operações de célula

  • copiar/colar células

  • dividir/mesclar células

• Células de markdown (para conteúdo de texto)

Salvando a saída de script em um arquivo de log

Quando você executa um script Python/HCL usando uma tarefa do robô, tem a opção de salvar a saída de script no arquivo de log que acompanha cada execução de tarefa. O log é um arquivo JSON com o mesmo nome que a tarefa (nome_tarefa.json).

Para ativar a opção, selecione Salvar saída do script no arquivo de log da execução da tarefa quando salvar, confirmar e enviar uma versão de um script. A opção pode ser configurada separadamente para cada versão de um script. Por isso, se quiser salvar a saída de script, confira se selecionou a opção para a versão do script específica que a tarefa executa.

Saída de script se refere a qualquer coisa contida no fluxo stdout produzido por um script. De modo geral, stdout é qualquer coisa que o script imprime ou exibe na tela quando você executa um script de forma interativa. Essencialmente, selecionando Salvar saída do script no arquivo de log da execução da tarefa, você capturará de forma permanente tudo o que é exibido na tela. Pode ser útil revisar essa saída capturada quando você está desenvolvendo scripts e solucionando problemas neles.

Informações adicionais:

• A opção se aplica apenas a tarefas Mesmo se você selecionar Salvar saída do script no arquivo de log da execução da tarefa no editor de scripts do Robôs, a opção será aplicada apenas a scripts executados por uma tarefa do robô. A opção não tem efeito quando você executa um script de forma interativa no editor de scripts.

• Mensagens de erro no arquivo de log de execução da tarefa As mensagens de erro de Python (o fluxo stderr) estão sempre incluídas no arquivo de log de execução da tarefa, independentemente de como você configurar Salvar saída do script no arquivo de log da execução da tarefa.

• Acessando o arquivo de log da execução da tarefa Um arquivo de log da execução da tarefa está disponível para cada execução da tarefa na guia Execuções de tarefas. Selecione uma execução da tarefa e, no painel lateral Detalhes da execução de tarefas, o arquivo de log aparecerá na seção Saída. É possível baixar o arquivo no computador para revisar.

Transição do ACLScript para Python e HCL

O Python é uma linguagem de programação de uso geral consideravelmente mais complexa que o ACLScript, uma linguagem de script simples criada para análise de auditorias.

Nossa intenção é que, com o tempo, a HCL replique muitos dos comandos e funções disponíveis no ACLScript. Para começar a usar o HCL, nossa biblioteca Python personalizada, você precisa ter pelo menos habilidades básicas de Python. Recomendamos um bom curso básico de Python para os que pretendem fazer a transição do ACLScript para Python/HCL.

Convenções de codificação do Python

Você precisará se habituar a determinadas convenções de codificação não necessárias no ACLScript, mas obrigatórias no Python e na HCL:

• Diferenciação de maiúsculas e minúsculas a sintaxe do Python e da HCL diferenciam maiúsculas e minúsculas, e a do ACLScript não.

  No Python:

  • print("Hello World!") funciona

  • PRINT("Hello World!") causa um erro

• Sem abreviações os nomes de funções, métodos e parâmetros do Python e do HCL devem ser escritos por extenso. Ao contrário do ACLScript, abreviações não são permitidas.

• Indentação é importante o Python usa indentação para implementar estruturas de controle, como declarações e loops condicionais. Uma indentação incorreta causa erros. O ACLScript ignora a indentação.

Bibliotecas externas Python

O Python é compatível com um grande número de bibliotecas externas, ou pacotes, que você pode instalar para ampliar a funcionalidade da instalação principal e da biblioteca padrão do Python. Uma biblioteca Python externa é uma coleção de módulos de código relacionados projetados para fazer coisas específicas além do que é possível fazer com os recursos e biblioteca padrão do Python. Ou agiliza e facilita certas atividades em relação à instalação principal do Python.

Bibliotecas externas incluídas no Python do Diligent One

A instalação do Python do Diligent One inclui certas bibliotecas externas por padrão. Você não precisa instalá-las explicitamente. Com exceção da própria biblioteca Python do HCL da Diligent, você precisa importar as bibliotecas pré-instaladas para usá-las na lógica de scripts Python/HCL subsequentes.

Bibliotecas externas pré-instaladas no ambiente Python do Diligent One:

Biblioteca	Descrição	Instruções de importação do Python
HCL	A biblioteca HCL (HighBond Command Language) é a biblioteca Python personalizada da Diligent para análises de dados voltadas a domínios e automação do Diligent One.	não obrigatório
Pandas	A biblioteca Pandas oferece um conjunto de ferramentas avançado para manipulação e análise de dados em Python, incluindo dataframes, que são matrizes bidimensionais de dados semelhantes a planilhas ou tabelas.	import pandas ou import pandas as pd (cria opcionalmente um alias curto do nome da biblioteca)
NumPy	A biblioteca NumPy oferece computação científica rápida e avançada em Python, incluindo operações algébricas e estatísticas básicas, operações matemáticas avançadas e criação/execução de cálculos em matrizes multidimensionais.	import numpy ou import numpy as np (cria opcionalmente um alias curto do nome da biblioteca)
Solicitações	A biblioteca Requests oferece uma sintaxe simples para fazer solicitações HTTP em Python e interagir com APIs baseadas na web.	import requests ou import requests as req (cria opcionalmente um alias curto do nome da biblioteca)
Cryptography	A biblioteca Cryptography permite a incorporação de algoritmos criptográficos em Python.	import cryptography ou import cryptography as crypt (cria opcionalmente um alias curto do nome da biblioteca)

Instalar as bibliotecas externas adicionais

Os robôs HighBond aceitam a instalação de outras bibliotecas externas além das pré-instaladas no ambiente Python do Diligent One. Para instalar uma biblioteca adicional, use o pip, uma ferramenta de download e instalação de pacotes Python. Por padrão, o pip baixa os pacotes do Python Package Index (PyPI), um repositório de código aberto de software Python. Você também pode usar pip para instalar pacotes de outros lugares.

Por exemplo, para instalar o pyexcel, uma biblioteca Python para trabalhar com arquivos e dados Excel, use este comando no editor de scripts do Robôs:

pip install pyexcel

Mesmo se você instalar uma biblioteca externa, não há garantia de que o editor de scripts do Robôs ofereça todas as funcionalidades da biblioteca externa. Por exemplo, ele talvez não aceite a exibição de gráficos e plotagens disponíveis em algumas bibliotecas externas.

Usar Python e HCL para trabalhar com APIs

Você pode usar scripts Python/HCL no Robôs para trabalhar com APIs de terceiros e com a própria API do Diligent One.

Trabalhando com uma API de terceiros

Para trabalhar com uma API de terceiros, comece importando a biblioteca Requests do Python no editor de scripts do Robôs:

import requests

Agora, você pode fazer solicitações de API usando a sintaxe de solicitações do Python e receber respostas. Para ver um exemplo simples do uso de Python para fazer uma solicitação de API de terceiros no Robôs, consulte Parte 3: Amplie seu alcance em Comece a usar os scripts do Robôs e a API do Diligent HighBond.

A explicação detalhada sobre como usar o Python com APIs de terceiros está além do escopo da nossa documentação. No entanto, há vários recursos on-line que podem oferecer orientações detalhadas.

Trabalhar com a API do HighBond

A API do HighBond é a interface de desenvolvedor para a Plataforma Diligent One. Você pode usar a API para automatizar as interações e o fluxo de trabalho do Diligent One, criar relatórios e integrar o Diligent One a outros sistemas da organização.

O HCL inclui métodos que simplificam a interação com a API do HighBond. Para obter mais informações, consulte Métodos do HCL para a API do HighBond.

Você também pode usar a biblioteca Requests do Python com a API do HighBond. No entanto, para maior facilidade e simplicidade, recomendamos usar os métodos do HCL.

Para ver um tutorial introdutório que abrange o uso de Python e HCL com a API do HighBond, consulte Começar a usar os scripts do Robôs e a API do Diligent HighBond.