REST Web Services package

Use as actions no REST Web Services package como métodos (DELETE, GET, PATCH, POST ou PUT) para enviar solicitações e receber respostas de uma API.

Configurações

As seguintes configurações estão disponíveis para as actions do REST Web Services. Defina as configurações apropriadas para enviar uma solicitação REST e receber uma resposta. Cada método requer parâmetros específicos.

Nota: Ao criar automações na plataforma macOS e usar actions como (DELETE, GET, PATCH, POST ou PUT), os seguintes modos de autenticação não são compatíveis:
  • Autenticação NTLM (Usuário AD)
  • Usuário AD Conectado
URI
Digite o URI para o recurso da API. Selecione uma das seguintes opções e defina as configurações conforme necessário:
  • Digite o URI: Digite o URI diretamente ou selecione o URI salvo como uma variável de string.
  • Selecionar credencial como URI: use essa opção para selecionar um URI que está salvo como uma credencial no Credential Vault. Use Credencial > Escolher para selecionar a credencial diretamente. Você também pode usar a opção Variável para selecionar uma credencial que esteja mapeada para uma variável de credencial. Essa opção permite que você oculte os URIs que contêm informações confidenciais, como códigos de autorização ou chaves de API.
Configuração de proxy
Defina as configurações de proxy para as ações do REST Web Services. Selecione uma das seguintes opções e defina as configurações conforme necessário:
  • Sistema: Selecione essa opção para permitir que o Bot Agent utilize o proxy do sistema. O proxy do sistema é o proxy que você configura na máquina do executor de bot onde a automação é executada.
  • Personalizar: Selecione essa opção para definir configurações de proxy personalizadas para a automação. Defina as seguintes configurações:
    • Host: o nome do host ou endereço IP do servidor proxy.
    • Porta: O número da porta do servidor proxy.
    • Nome de usuário (opcional): O nome de usuário para autenticar o servidor proxy.
    • Senha (opcional): A senha para autenticar o servidor proxy.
    Nota: Você deve configurar o Nome de usuário e a Senha para qualquer servidor proxy autenticado.
    Você pode usar uma das opções Credencial, Variável ou String insegura para definir as configurações de proxy.
    • Credencial: Para selecionar um valor disponível no Credential Vault.
    • Variável: Para selecionar a variável de credencial que é mapeada para um valor.
    • String insegura: Para inserir o valor manualmente ou selecionar um valor que seja mapeado para uma variável de string predefinida.
Modo de autenticação
Defina as configurações de autenticação para as ações do REST Web Services. Selecione uma das seguintes opções e defina as configurações conforme necessário:
  • Sem Autenticação: Selecione essa opção para acessar os endpoints que não exigem autenticação para acessar seus servidores.
  • Token de usuário da Control Room: Selecione essa opção para usar o token gerado ao fazer login na Control Room.
  • Básico: Selecione essa opção para inserir o Nome de usuário e a Senha para autenticar as chamadas de API do REST Web Services. Essa opção adiciona um cabeçalho chamado Autorização que contém uma representação em string codificada em base64 do Nome de usuário e Senha à chamada da API.
  • Usuário logado do AD: Selecione essa opção para escolher a autenticação baseada no Active Directory (AD). Os usuários do AD que estão autorizados a acessar a API relacionada são autenticados usando o AD. Nenhuma credencial é necessária na solicitação.
  • Autenticação (usuário do AD) do Windows NT LAN Manager (NTLM): Selecione essa opção para escolher uma autenticação NTLM de desafio-resposta. Defina as seguintes configurações:
    • Domínio: digite o domínio no qual a chamada de API deve ser autenticada. Você também pode selecionar uma variável de string que seja mapeada para o domínio ou o host.
    • Nome de usuário (opcional): O nome de usuário para autenticar a chamada da API.
    • Senha (opcional): A senha para autenticar a chamada da API.
    Você pode usar uma das opções Credencial, Variável ou String insegura para configurar o nome de usuário e a senha. Recomendamos que você use a opção Credencial para escolher uma credencial do Credential Vault ou use uma variável de credencial.
  • OAuth2 — Control Room gerenciada: Selecione essa opção para escolher uma conexão OAuth gerenciada pela Control Room como a opção de autenticação. Para mais detalhes, consulte Configure OAuth connections in Control Room.

    O vídeo a seguir mostra como usar a OAuth conexão em REST Web Services:

Cabeçalho
Adicione cabeçalhos personalizados para incluir metadados adicionais nas solicitações da API. nem todos os métodos exigem um cabeçalho. Você pode adicionar cabeçalhos como Autorização, Conjunto de Caracteres de Aceitação, Tipo de Conteúdo, Controle de Cache, Agente do Usuário, etc.

Clique em Adicionar cabeçalho e siga as instruções no modal Cabeçalho personalizado para adicionar os cabeçalhos necessários. Você pode selecionar uma credencial armazenada no Credential Vault, ou variável de credencial, ou inserir o cabeçalho diretamente como uma string insegura.

Tipo de conteúdo
O cabeçalho Tipo de conteúdo define o tipo de mídia do conteúdo no corpo da solicitação. As actions REST Web Services oferecem suporte aos seguintes tipos de conteúdo:
  • application/x-www-form-urlencoded: codifica os parâmetros no formato de string de consulta de URL.
  • JSON (aplicação/json): insira um corpo de solicitação no formato JSON.
  • XML (aplicação/xml): insira um corpo de solicitação no formato XML.
  • Texto (texto/simples): insira um corpo de solicitação do tipo texto em formato de texto simples.
  • XML (texto/xml): insira um corpo de solicitação do tipo texto no formato XML.
  • HTML (texto/html) insira um corpo de solicitação do tipo texto em formato HTML.
  • multipart/form-data: permite incluir tanto texto quanto arquivos no corpo da solicitação. Esse tipo de conteúdo oferece suporte a todos os formatos de arquivo compatíveis com a API. Você pode usar esse tipo de conteúdo para enviar várias partes em uma única solicitação, normalmente incluindo dados de texto (como campos de formulário) e, possivelmente, um upload de arquivo. Esse tipo de conteúdo também é compatível com a transmissão de arquivos.
    Um fluxo de arquivo pode ser lido depois de atribuí-lo a uma variável de tipo de arquivo. Por exemplo, você pode ler um fluxo de arquivos atribuído a uma variável em um local do OneDrive. Para obter mais informações, consulte A action Atribuir arquivo.
    FileStream dos Serviços Web REST
  • Binário: Usar Binary para enviar arquivos brutos, como imagens, vídeos e arquivos de áudio. Você pode enviar os arquivos usando uma das seguintes opções:
    • Variável: atribua uma variável para fazer upload de um arquivo da área de trabalho ou de dentro da Control Room. Você também pode usar essa opção para transmitir arquivos de um local de armazenamento.
    • Arquivo da Control Room: envie um arquivo disponível no armazenamento da Control Room.
    • Arquivo de desktop: Carregue um arquivo diretamente de sua área de trabalho.
  • Personalizar
    Personalizar: adicione conteúdo personalizado que não se enquadre no tipo de conteúdo padrão. Por exemplo, ao migrar da v.11.x para Automation 360, o valor a seguir não se enquadra em nenhum dos tipos de conteúdo padrão: application/vnd.whispir.message-v1+json

Para application/x-www-form-urlencoded e multipart/form-data, clique em Adicionar parâmetro e siga as instruções no modelo Parâmetro para adicionar os parâmetros de cabeçalho necessários.

Para outros tipos de conteúdo, você pode usar a opção Inserir os parâmetros ou a opção Selecionar credencial como parâmetros para adicionar os parâmetros. A opção Selecionar credencial como parâmetros permite que você adicione dados confidenciais como cabeçalhos de solicitação.

Adicionar substituição
A opção Adicionar substituição permite que você insira variáveis no corpo da solicitação REST. Essa opção está disponível para cabeçalhos JSON (aplicação/json), XML (aplicação/xml), Texto (texto/simples), XML (texto/xml), HTML (texto/html) e tipo de conteúdo Personalizado.
Uma variável é uma representação simbólica de dados e permite que você acesse um valor sem precisar inseri-lo manualmente sempre que precisar. Por exemplo, considere a seguinte solicitação de corpo REST:
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
No corpo da solicitação acima, você pode substituir as variáveis entre colchetes clicando em Adicionar substituição e adicionando os valores necessários.
Opções avançadas
Capturar resposta de falha: marque esta caixa de seleção para capturar a resposta de falha, exceto para a resposta Êxito/Ok. O sistema captura os detalhes da resposta de falha no corpo da resposta. Essa opção está disponível nas ações dos métodos Excluir, Obter, Corrigir, Publicar e Colocar.
Permitir conexão insegura ao usar https: Marque esta caixa de seleção para permitir uma conexão insegura ao usar o protocolo https. Essa opção está disponível em todas as ações.
Aceitar cookies: Marque a caixa de seleção para fazer a captura automática de cookies de sessão das respostas do servidor. Os seguintes recursos são ativados em segundo plano quando você marca esta caixa de seleção.
  • Capturar: O sistema captura cookies de sessão que o servidor inclui nas respostas.
  • Armazenamento seguro: O sistema criptografa os cookies capturados na memória do processo, garantindo que eles nunca sejam armazenados permanentemente e fiquem inacessíveis fora da sua sessão de automação.
  • Reuso: O sistema inclui automaticamente os cookies nas chamadas REST subsequentes, eliminando o manuseio manual de cookies e melhorando a confiabilidade da automação.
  • Processamento de vários cookies: O sistema permite que a automação lide com vários cookies que o servidor retorna, garantindo que todas as credenciais de autenticação necessárias sejam incluídas.
  • Destruição: O sistema destrói automaticamente os cookies capturados quando a sessão de automação termina ou a execução do bot é concluída, garantindo a segurança e a privacidade dos dados.

Essa opção está disponível nas ações dos métodos Excluir, Obter, Corrigir, Publicar e Colocar.

Nota: Os cookies capturados são específicos do domínio de origem e não serão usados automaticamente para chamadas REST subsequentes feitas para domínios diferentes. Isso significa que os cookies capturados de domainA.com não serão utilizados para solicitações a domainB.com.
Fazer download de arquivo: Marque esta caixa de seleção para baixar o arquivo binário disponível no URI para um local específico. Certifique-se de inserir o caminho do arquivo desejado com o nome e a extensão. Por exemplo: <C:/Users/Downloads/image01.jpg>

Essa opção está disponível apenas na ação do método Obter. O sistema exibe uma mensagem de erro quando um dos seguintes cenários ocorre:

  • URI inválido: se o URI fornecido estiver incorreto.
  • Arquivo não encontrado: se a resposta da API estiver vazia porque o arquivo não existe no local especificado.
  • Permissões insuficientes: se você não tiver permissão de gravação no local de download.
  • Extensão de arquivo não correspondente: se a extensão do arquivo não corresponder ao tipo esperado.

Marque a caixa de seleção Substituir arquivo se já existir para substituir um arquivo existente por uma nova versão.

Aguardar a conclusão da ação
você pode definir um valor de tempo esgotado ao enviar uma solicitação REST e receber uma resposta. Ao executar ações como actions como PUBLICAR, COLOCAR, EXCLUIR, CORRIGIR E OBTER, especifique o tempo de espera (em milissegundos) no campo Aguardar a conclusão da ação. Por padrão, o tempo de espera é de 60.000 milissegundos
Configuração de SSL/TLS
Use essa opção para fazer upload de um arquivo de certificado com ou sem uma senha para proporcionar autenticação adicional durante as chamadas à REST API.

A configuração SSL/TLS usa o protocolo TLS mútuo (mTLS) para criptografar, autenticar e proteger as comunicações entre o URI da API e o cliente. O mTLS exige que ambas as entidades se autentiquem mutuamente por meio da troca de certificados. A transmissão de dados ocorre somente se ambas as entidades autenticarem com êxito os certificados trocados.

O REST Web Services é compatível com certificados do tipo .p12 para máquinas Windows e no formato .pfx para máquinas não Windows.

  • Caminho do arquivo do repositório de chaves (opcional): Carregue o arquivo de certificado usando a opção Variável, Arquivo da Control Room ou Arquivo de desktop.
  • Senha do repositório de chaves (opcional): Se o certificado estiver protegido por senha, você pode autenticar a senha do certificado usando a opção Credencial, Variável ou String insegura. Para mais informações sobre como armazenar senhas com segurança no cofre de credenciais, consulte Credenciais e lockers no Credential Vault.
Atribuir a saída a uma variável
a saída de resposta é capturada em uma variável de dicionário. Uma variável de dicionário é um par de valores chave. Use o nome do cabeçalho de resposta como chave para retornar o valor do cabeçalho, ou o “Corpo”, como a chave para retornar o corpo de resposta.

Essa opção está disponível nas ações dos métodos Excluir, Obter, Corrigir, Publicar e Colocar.

Nota: A chave de resposta, com seu valor, está disponível na variável de dicionário para exibição do status de resposta da API REST.
Para obter uma lista dos nomes de cabeçalho para o recurso da API, execute estas etapas:
  1. Insira uma Loop action após a REST Web Services action.
  2. Selecione o iterador Para cada chave no dicionário.
  3. No campo Variável de dicionário, selecione a variável que contém a saída da REST Web Services action.
  4. Atribua o valor de cada chave a $prompt-assignment$.
  5. Inserir uma action Registrar texto no arquivo.
  6. Forneça o caminho do arquivo para armazenar a lista de nomes de cabeçalho em um arquivo de texto.
  7. Insira $prompt-assignment$ no campo Digite o texto para registrar.
  8. Selecione a opção Substituir arquivo existente.
  9. Clique em Salvar.

    Quando você executa o bot, ele imprime os nomes de cabeçalho do recurso da API para o arquivo selecionado.

Atribuir arquivo a uma variável
Essa opção está disponível apenas na ação Obter fluxo de arquivos. A ação Obter fluxo de arquivos permite que você atribua uma variável ao arquivo disponível no URI. Você pode então usar essa variável de arquivo em quaisquer ações subsequentes dentro da sessão. Para mais informações sobre a atribuição de uma variável de arquivo, consulte Usar a ação Obter fluxo de arquivos.

Como passar valores com segurança

Você pode passar valores de forma segura do Credential Vault para o serviço da web especificando o locker, as credenciais e o atributo nos seguintes campos de action compatíveis:
  • URI
  • Cabeçalhos personalizados
  • Corpo: Para o tipo de conteúdo application/x-www-form-urlencoded, clique em Adicionar parâmetro para selecionar o valor do arquivo Credential Vault.

    Para todos os outros tipos de conteúdo, selecione a opção Selecionar credencial como parâmetros e clique em Escolher.

Actions no REST Web Services package

Action Descrição
Método DELETE Remove o recurso identificado pelo URI.
Método GET Recupera as informações identificadas pelos parâmetros incluídos no URI. Não há Tipo de conteúdo para o método GET, pois todos os parâmetros são passados como parte do URI.

Limitações e características do método GET incluem:

  • o comprimento do URI é limitado em 2.048 caracteres.
  • Todos os parâmetros são passados no URI.
  • O método GET expõe dados que estão no URI, o que faz dele menos seguro do que o método POST.
  • O GET não altera nenhum dado, tornando-o seguro para todos os usuários, seja qual for sua autorização.

Consulte Usando o método Get.
Método Patch Modifica o recurso identificado pelo URI.
Método POST Cria um novo recurso no URI.
  • Os parâmetros são passados no corpo da solicitação.
  • Não há limite de comprimento para o corpo da solicitação.

Consulte Usar o método Post.
Método PUT Atualiza ou substitui um recurso com base nos parâmetros passados no URI ou no corpo. Consulte Usar o método Put.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See Conectar o Bot Agent a um dispositivo com um proxy.