Partilhar via

Fazer solicitações HTTP

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

Pré-requisitos

Utilizar o nó de pedido HTTP

  1. Selecione o ícone Adicionar nó em baixo do nó depois do qual deseja chamar uma API externa, aponte para Avançado e selecione Enviar solicitação HTTP.

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

  3. Na lista pendente, selecione o método de pedido apropriado. Os métodos GET, POST, PATCH, PUT e DELETE são suportados.

    Captura de ecrã do URL da API concluído e da lista pendente do método

  4. Em Cabeçalhos e corpo no nó, selecione o botão Editar, que abre o painel de Propriedades do pedido 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 ecrã da lista dos pares de valores das chaves de cabeçalhos para o nó HTTP.

    Você pode usar a seção de cabeçalhos para passar tokens de autenticação, tipo de conteúdo ou quaisquer outros cabeçalhos necessários para a API que você está chamando. Por exemplo, você pode adicionar um cabeçalho como Authorization: Bearer <your_token> para autenticar a solicitação.

  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 o 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 está chamando. Ele gera uma variável Power Fx, permitindo que você a use em outro lugar em sua tela de criação, com suporte intellisense no editor Power Fx. Selecione De dados de exemplo e, em seguida, selecione Obter esquema de JSON de exemplo. Cole a resposta de exemplo no editor e selecione Confirmar.

  8. Em Salvar resposta do usuário 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 do pedido HTTP.

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

    Captura de ecrã da lista pendente 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. Este 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, permitindo que você inclua valores dinâmicos e variáveis de referência. Selecione o botão Editar JSON , escolha Fórmula e insira um objeto Power Fx (qualquer JSON existente que foi inserido é convertido em um objeto Power Fx para você), que é convertido em JSON quando a solicitação HTTP é feita.

      Captura de ecrã do conteúdo JSON selecionado para o tipo de conteúdo principal.

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

      Captura de ecrã do conteúdo RAW selecionado para o tipo de conteúdo do corpo.

Processamento de erros e limite de sessão

O nó 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 não é executada, o agente interrompe sua operação e dispara o tópico do sistema On Error , exibindo uma mensagem de erro.

No entanto, pode configurar o processamento de erros para não acionar o tópico do sistema Em caso de erro. Em vez disso, você pode fazê-lo armazenar o código de status HTTP e qualquer corpo de resposta de erro em variáveis que você especificar. Você pode interrogar essas variáveis conforme necessário, e o tópico pode continuar a ser executado. Essa configuração é útil em cenários em que você deseja que o agente continue a operação, mesmo que uma solicitação HTTP específica falhe.

Para configurar o comportamento de processamento de erros de um nó de Pedido HTTP:

  1. Em Cabeçalhos e corpo, selecione Editar. O painel Propriedades da Solicitação HTTP é exibido.

  2. Em Tratamento de erros, selecione o comportamento desejado: Gerar um erro ou Continuar no erro.

  3. Se você selecionar Continuar no erro, configure as variáveis para o código de status e o corpo da resposta do erro.

    Captura de ecrã do painel 'Propriedades da solicitação HTTP' para um nó 'Solicitação HTTP' mostrando a configuração de tratamento de erros, para continuar em caso de erro. As variáveis para o código de status e o corpo da resposta de erro são selecionadas.

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

O tipo de variável de resposta de erro é Any. Pode usar um nó de valor de análise para converter essa variável para um registo Power Fx.

No painel Propriedades da solicitação HTTP , você também pode definir uma propriedade Tempo limite da solicitação , em milissegundos. O valor padrão é 30 segundos.

  • Last updated on