Fazer solicitações HTTP

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

Pré-requisitos

• Criar e editar tópicos

Use o nó de solicitação HTTP

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

   

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.

   

4. Em Cabeçalhos e corpo no nó, selecione o botão Editar, que abre o painel propriedades de 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.

   

   Você pode usar a seção 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> 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 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.

8. Em Salvar resposta do usuário como , escolha onde você 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 propriedades de 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.

   

   • 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.

     

   • 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.

     

Tratamento de erros e tempo limite

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 dispara o tópico do sistema Se Houver Erro, exibindo uma mensagem de erro.

No entanto, você pode configurar o tratamento de erros para não disparar o tópico do sistema Se Houver Erro. Em vez disso, você pode fazer com que ele armazene 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 se uma solicitação HTTP específica falhar.

Para configurar o comportamento de tratamento de erros de um nó de Solicitação HTTP:

1. Em Cabeçalhos e corpo, selecione Editar. O painel de 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 variáveis para o código de status e o corpo da resposta ao erro.

   

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

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

No painel de propriedades Solicitação HTTP, você também pode definir uma propriedade Solicitação de tempo limite, em milissegundos. O valor padrão é 30 segundos.