Serviços web REST pacote

Use as ações no Serviços web REST pacote como métodos (DELETE, GET, PATCH, POST ou PUT) para enviar solicitações e receber respostas de uma API.

Como trabalhar com Serviços web REST ações

Forneça as seguintes informações para enviar uma solicitação REST e receber uma resposta. Nem todos os parâmetros são necessários para todos os métodos.
  • Digite o URI: um endereço exclusivo para um recurso de API.
  • Configuração de proxy: para definir o proxy, selecione a guia Sistema ou Personalizar da configuração Proxy.
    Opção Descrição
    Sistema

    Proxy do sistema é o proxy configurado na máquina executora bot onde o bot está sendo executado.

    Se esta opção for selecionada, o Agente de bot utiliza o proxy do sistema.
    Personalizar

    Esta opção permite definir configurações de proxy personalizadas dentro das ações Serviços web REST. Por exemplo, se uma REST API precisar ser roteada por meio de um proxy diferente do proxy do sistema, você poderá selecionar a opção Personalizar e fornecer detalhes de proxy nas ações REST.

    Forneça os seguintes detalhes:

    • Host: o nome do host ou endereço IP do proxy
    • Porta: o número da porta do proxy
    • Nome de usuário (opcional): o nome de usuário usado para a autenticação de proxy
    • Senha (opcional): a senha usada para a autenticação do proxy
      Nota: Se o proxy a ser configurado for um proxy autenticado, você deverá fornecer credenciais de autenticação nos campos Nome de usuário e Senha.
    Para os campos Host, Porta, Nome do usuário, e Senha escolha entre a guia Credencial, Variável, ou String insegura:
    • Credencial: Use um valor disponível no cofre de credenciais.
    • Variável: use uma variável que armazena um valor de credencial em uma variável definida pelo usuário.
    • String insegura: especifique manualmente o valor que você deseja usar.
  • Modo de autenticação: há suporte para três modos de autenticação:
    • Sem Autenticação: use esta opção para acessar os terminais que não requerem autenticação para acessar seus servidores.
    • Token de usuário da Control Room: as Serviços web REST ações usam o token gerado ao fazer login na Control Room para acessar os endpoints.
    • Básico: básico é a maneira mais simples de autenticar usuários. Ao selecionar esta opção, você digitará o nome de usuário e a senha. Essa técnica usa um cabeçalho chamado Authorization, com uma representação codificada em base64 do nome de usuário e da senha inseridos.
    • Usuário logado do AD: usuários do Active Directory (AD) autorizados a acessar a API correspondente são autenticados por meio do AD. Nenhuma credencial é necessária na solicitação.
    • Autenticação (usuário do AD) do Windows NT LAN Manager (NTLM): método de autenticação de desafio/resposta que permite aos clientes fornecer o nome de usuário e senha como credenciais ou texto sem formatação criptografados. Recomenda-se usar as credenciais armazenados no Automation Anywhere Credential Vault.
    • OAuth2 — Control Room gerenciada: quando você integra o OAuth com a Control Room, é possível gerenciar de maneira centralizada e armazenar com segurança os tokens usados para autenticação com provedores terceirizados. Você deve configurar o serviço web e anotar os detalhes de autenticação (como ID do cliente, segredo do cliente, URL de autorização etc.) para usar a conexão OAuth na Control Room. Para mais detalhes, consulte Configurar conexões OAuth na Control Room

      O vídeo a seguir mostra como usar a OAuth conexão em Serviços web REST:

  • Cabeçalho: nem todos os métodos exigem um cabeçalho. Os cabeçalhos representam os metadados associados à solicitação.
  • Tipo de conteúdo: Quando um cabeçalho contém um tipo de conteúdo, define a negociação de conteúdo entre o cliente e o servidor. As Serviços web REST ações são compatíveis com os seguintes tipos de conteúdo
    • application/x-www-form-urlencoded: codifique os parâmetros na URL.
    • JSON (aplicação/json): Insira um corpo de solicitação JSON.
    • XML (aplicação/xml): insira um corpo de solicitação XML.
    • Texto (texto/simples)
    • XML (texto/xml)
    • HTML (texto/html)
    • multipart/form-data:
      • envie dados binários, na maioria dos casos para carregar arquivos para o servidor. Ele é usado nos casos em que você envia várias partes em uma única solicitação, normalmente incluindo dados de texto (como campos de formulário) e potencialmente um upload de arquivo. Você também pode usar uma variável FileStream. Veja abaixo mais informações.
      • FileStream: O FileStream pode ser lido após atribuí-lo a uma variável. Por exemplo, você pode ler um FileStream atribuído a uma variável em um local do OneDrive. Para obter mais informações, consulte A ação Atribuir arquivo.
        FileStream dos Serviços Web REST
    • Binário: Usar Binary para enviar arquivos brutos, como imagens, vídeos e arquivos de áudio. Quando você seleciona Binary, poderá fazer upload de um arquivo binário (como uma variável, um arquivo da Control Room ou um arquivo de desktop).
    • 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
  • Adicionar substituição: permite inserir variáveis no corpo da solicitação REST. 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. Os detalhes da resposta de falha são capturados no corpo de resposta.
    • Permitir conexão insegura ao usar https: marque esta caixa de seleção para permitir uma conexão insegura ao usar https.
    • Aceitar cookies: marque a caixa de seleção para fazer a captura automática de cookies de sessão das respostas do servidor.
      • Capturar: quando ativado, o recurso captura cookies de sessão incluídos nas respostas do servidor.
      • Armazenamento seguro: os cookies capturados são criptografados na memória do processo, garantindo que nunca sejam armazenados permanentemente e fiquem inacessíveis fora da sua sessão de automação.
      • Reuso: os cookies são incluídos automaticamente nas chamadas REST subsequentes, eliminando o manuseio manual de cookies e melhorando a confiabilidade da automação.
      • Processamento de vários cookies: o recurso processa de maneira contínua vários cookies retornados pelo servidor, garantindo que todas as credenciais de autenticação necessárias sejam incluídas.
      • Destruição: os cookies capturados são destruídos automaticamente quando a sessão de automação termina ou o bot termina a execução, garantindo a segurança e privacidade dos dados.
      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: (Disponível apenas com o método GET) marque a caixa de seleção para baixar o arquivo em um local específico. O URI deve retornar/baixar um arquivo. Digite o caminho da pasta desejada e o nome do arquivo com a extensão. Certifique-se de usar a extensão de arquivo correta. Por exemplo: C:/Usuários/Downloads/imagem01.jpg
      Dica: Marque a opção Substituir arquivo se já existir para substituir um arquivo com o mesmo nome que já existe na pasta em que você está salvando o arquivo.
      Gerenciamento de erros:
      URI inválido:
      Se o URI fornecido estiver incorreto, uma mensagem de erro será exibida.
      Arquivo não encontrado:
      Se a resposta da API estiver vazia porque o arquivo não existe no local especificado, será exibida uma mensagem de erro.
      Permissões insuficientes:
      Se você não tiver permissões de gravação para o local de download, será exibida uma mensagem de erro.
      Extensão de arquivo não correspondente:
      Se a extensão do arquivo não corresponder ao tipo esperado, será exibida uma mensagem de erro.
  • Aguarde a ação para concluir: você pode definir um valor de tempo esgotado ao enviar uma solicitação REST e receber uma resposta. Ao executar ações, tais como POST, PUT, DELETE, PATCH e GET, no campo Aguarde a ação para conclui, você pode especificar o tempo de espera (em milissegundos). Por padrão, o tempo de espera é de 60000 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 Serviços web REST é 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 cofres no Credential Vault.
  • Variáveis de saída: 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.
    Nota: A chave de resposta, com seu valor, está disponível na variável de dicionário para exibição do status de resposta de REST API.
    Para obter uma lista dos nomes de cabeçalho para o recurso da API, execute estas etapas:
    1. Insira uma Loop ação após a Serviços web REST ação.
    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 Serviços web REST ação.
    4. Atribua o valor de cada chave a $prompt-assignment$.
    5. Inserir uma ação 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.

Como passar valores com segurança

Você pode passar valores de forma segura do Credential Vault para o serviço da web especificando o cofre, as credenciais e o atributo nos seguintes campos de ação 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.

Ações no Serviços web REST pacote

Ação 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.

Suporte a proxy

Se o dispositivo estiver configurado com um proxy, todas as solicitações de saída desse pacote serão roteadas por meio do servidor de proxy. Consulte Conectar o Agente de bot a um dispositivo com um proxy.