Compartilhar via

Fazer solicitações HTTP

  • Artigo

Em Copilot Studio, você pode estender os recursos de um agente chamando APIs REST externas usando o nó solicitação HTTP . Esta chamada pode ser útil quando você precisar recuperar dados de um sistema externo ou manipular dados nesse sistema.

Pré-requisitos

Use o nó de solicitação HTTP

  1. Selecione Adicionar nó (+), abra o submenu Avançado e selecione Enviar solicitação HTTP.

    Captura de tela da opção Enviar solicitação HTTP no menu avançado.

  2. Na caixa URL, informe a URL do ponto de extremidade da API que você deseja chamar.

  3. Selecione o Método de solicitação apropriado da lista suspensa. Há suporte para os métodos GET, POST, PATCH, PUT e DELETE.

    Captura de tela do URL da API concluído e do menu suspenso de métodos

  4. Em Cabeçalhos e corpo no nó, selecione o botão Editar, que abre o painel de propriedades da solicitação HTTP.

  5. Opcionalmente, você pode adicionar um ou mais cabeçalhos à solicitação HTTP. Selecione o botão Adicionar para adicionar a chave e o valor de cada cabeçalho.

    Captura de tela da lista de pares de valores-chave de cabeçalhos do nó HTTP.

  6. Por padrão, nenhum conteúdo é enviado no corpo da solicitação HTTP, mas você pode especificar o conteúdo no corpo.

  7. No nó, escolha Tipo de dados de resposta entre as opções disponíveis.

    Você pode fornecer um exemplo de resposta JSON, que geralmente pode ser encontrado na documentação da API que você está chamando. Ele gera uma variável do Power Fx, permitindo que você a use em outro lugar na tela de criação, com suporte ao intellisense no editor do Power Fx. Selecione Dos Dados de Exemplo e escolha Obter esquema do JSON de exemplo. Cole a resposta de exemplo no editor e selecione Confirmar.

    Captura de tela de Obter esquema do editor JSON de exemplo.

  8. Em Salvar resposta como escolha onde deseja que a resposta da solicitação HTTP seja armazenada, criando uma nova variável ou selecionando uma existente.

Enviar conteúdo no corpo da solicitação HTTP

  1. Em Cabeçalhos e corpo no nó, selecione o botão Editar, que abre o painel de propriedades da solicitação HTTP.

  2. Em Corpo, selecione o tipo de conteúdo apropriado. Por padrão, Corpo é definido como Sem Conteúdo, onde nenhum conteúdo deve estar presente na corpo da solicitação, que é mais comumente usada com a solicitação GET. Para adicionar conteúdo ao corpo, selecione uma das opções disponíveis.

    Captura de tela do menu suspenso de opções de conteúdo do corpo

    • Conteúdo JSON: o conteúdo JSON permite fornecer um objeto JSON no corpo da solicitação. Esse objeto é frequentemente usado ao fazer solicitações POST ou PUT. Quando essa opção é selecionada, um editor permite que você insira seu conteúdo JSON.

      Você também pode especificar seu conteúdo JSON usando o Power Fx, o que permite incluir valores dinâmicos e variáveis de referência. Select o botão Editar JSON, escolha Fórmula e insira um objeto do Power Fx (qualquer JSON existente inserido é convertido em um objeto Power Fx para você), que é convertido em JSON quando a solicitação HTTP é feita.

      Captura de tela do conteúdo JSON selecionado para tipo de conteúdo de corpo.

    • Conteúdo bruto: o conteúdo bruto permite inserir uma cadeia de caracteres de dados no corpo da solicitação, e essa cadeia de caracteres pode ser qualquer tipo de conteúdo que você especificar. O conteúdo bruto é inserido usando uma fórmula do Power Fx, como o conteúdo da cadeia de caracteres mostrado no exemplo a seguir.

      Captura de tela do conteúdo RAW selecionado para tipo de conteúdo de corpo.

Tratamento de erros e timeout

O nó da solicitação HTTP tem várias opções para lidar com situações em que a solicitação HTTP pode falhar ou retornar um erro.

Por padrão, o recurso "gera um erro". Isso significa que quando uma solicitação HTTP retorna um erro ou falha na execução, o agente interrompe sua operação e aciona o Erro tópico do sistema, exibindo uma mensagem de erro.

No entanto, você pode configurar o tratamento de erros para não disparar o tópico do sistema de Erro. Em vez disso, ele preenche o código de status HTTP e qualquer corpo da resposta de erro em variáveis que você especificar, permitindo interrogar essas variáveis, conforme necessário, e para que o tópico continue a ser executado. Essa configuração é útil em cenários onde você deseja que o agente continue operando, mesmo que uma solicitação HTTP específica falhe.

Para configurar o comportamento de tratamento de erros.

  1. Em Cabeçalhos e corpo no nó, selecione o botão Editar, que abre o painel de propriedades da solicitação HTTP.

  2. Escolha o comportamento desejado na lista suspensa Manipulação de erros.

  3. Se você escolher Continuar em caso de erro, configure as variáveis Código de status e Corpo da resposta do erro, criando novas variáveis ​​ou selecionando variáveis ​​existentes no seletor.

    Captura de tela do tratamento de erros configurado para continuar em caso de erro com variáveis ​​especificadas para código de status e corpo de resposta de erro.

Neste exemplo de código, se a solicitação HTTP falhar, o agente armazena o código de status HTTP na variável Topic.StatusCode , e o corpo da resposta na variável Topic.ErrorResponse . O agente continua com seus próximos passos no tópico.

O tipo de variável Resposta de erro é Qualquer. Você pode usar o nó Analisar Valor para converter essa variável em um registro do Power Fx.

O painel de propriedades também contém uma propriedade Tempo limite da solicitação, que aceita um valor em milissegundos. O valor padrão é 30 segundos, mas você pode alterar esse valor, se necessário.