Criar um conector personalizado de uma coleção Postman

Observação

Este artigo faz parte de uma série de tutoriais sobre como criar e usar conectores personalizados no Azure Logic Apps, Microsoft Power Automate e Microsoft Power Apps e como usar conectores habilitados para IA em Microsoft Copilot Studio. Certifique-se de ler a visão geral do conector personalizado para entender o processo. Acesse Usar Power Platform conectores em Copilot Studio para saber como você pode chamar os conectores como ações de conector em seu Microsoft Copilot agente.

Para criar um conector personalizado, você deve descrever a API à qual deseja se conectar para que o conector entenda as estruturas de dados e as operações da API. Neste tópico, você cria um conector personalizado usando uma coleção Postman que descreve a Cognitive Services Text Analytics Sentiment API (nosso exemplo para esta série).

Para outras maneiras de descrever uma API, acesse os seguintes tópicos:

• Crie um conector personalizado a partir de uma OpenAPI definição

• Crie um conector personalizado do zero

Pré-requisitos

Não deixe de revisar todos os pré-requisitos para garantir que você tenha o que precisa para criar um conector personalizado. Você precisará:

• Uma coleção do Postman que descreve a API de exemplo. Você tem duas opções:

  • Baixe a coleção Postman que criamos.
    or
  • Conclua o tópico Criar uma coleção do Postman para um conector personalizadoObserve que, ao criar um conector personalizado, a coleção do Postman não deve ser maior que 1 MB.

• Uma chave de API para a API de análise de texto dos serviços cognitivos.

• Uma das assinaturas a seguir:

  • Azure, se você estiver usando o Logic Apps
  • Power Automate
  • Power Apps

• Se você estiver usando o Logic Apps, primeiro crie um conector personalizado do Azure Logic Apps.

Importar a coleção Postman

Agora você está pronto para trabalhar com a coleção Postman que você criou ou baixou. Muitas das informações necessárias estão presentes na coleção. Também é possível analisar e atualizar essas informações à medida que usa o assistente de conector personalizado. Comece importando a coleção Postman para Logic Apps ou para Power Automate e Power Apps.

Importar a coleção Postman para Aplicativos Lógicos

1. Acesse o portal do Azure e abra o conector do Logic Apps que você criou anteriormente em Criar um conector personalizado do Azure Logic Apps.

2. No menu do seu conector, escolha Logic Apps Connector e, em seguida, escolha Editar.

   

3. Em Geral, escolha Carregar coleção Postman V1 e navegue até a coleção Postman que você criou.

   

   O assistente importa a coleção e a converte em uma OpenAPI definição chamada generatedApiDefinition.swagger.json.

Observação

Este tutorial se concentra em uma API REST, mas você também pode usar uma API SOAP com aplicativos lógicos.

Importar a coleção Postman para o Power Automate e o Power Apps

1. Acesse make.powerapps.com ou flow.microsoft.com.

2. No painel de navegação, selecione Dados > Conectores personalizados.

3. Escolha Novo conector personalizado e depois escolha Importar uma coleção do Postman.

4. Insira um nome para o conector personalizado, navegue até a coleção Postman que você baixou ou criou e escolha Continuar.

   

   Parâmetro	Valor
   Título do conector personalizado	"SentimentDemo"

   O assistente importa a coleção e a converte em uma OpenAPI definição chamada generatedApiDefinition.swagger.json.

Atualizar detalhes gerais

A partir desse ponto, será exibida a interface do usuário do Power Automate, mas as etapas são basicamente as mesmas em todas as três tecnologias. Destacaremos todas as diferenças.

1. Na página Geral , revise as informações que foram importadas da coleção Postman, incluindo o host e a URL base da API. O conector usa o host e a URL base para determinar como chamar a API.

   Observação

   Para obter mais informações sobre como se conectar a APIs locais, consulte Conectar-se a APIs locais usando o gateway de dados.

2. Atualize a descrição para algo significativo. Essa descrição é exibida nos detalhes do conector personalizado e pode ajudar outros usuários a entender como o conector pode ser útil para eles.

   Parâmetro	Valor
   Descrição	"Usa a API de Sentimento da Análise de Texto dos Serviços Cognitivos para determinar se o texto é positivo ou negativo."

Especificar o tipo de autenticação

Há várias opções disponíveis para a autenticação nos conectores personalizados. As APIs de Serviços Cognitivos usam a autenticação de chave de API.

1. Na página Segurança, em Tipo de autenticação, escolha Chave de API.

2. Na Chave de API, especifique um rótulo de parâmetro, o nome e o local. Escolha um rótulo significativo e relevante. Esse texto será exibido aos usuários para orientá-los a fazer conexões usando o conector personalizado. O nome e o local do parâmetro devem corresponder ao que a API espera (nesse caso, o cabeçalho especificado no Postman). Escolha Conectar.

   

   Parâmetro	Valor
   Rótulo de parâmetro	"Chave API"
   Nome do parâmetro	"Ocp-Apim-Subscription-Key"
   Localização do parâmetro	"Cabeçalho"

3. Na parte superior do assistente, certifique-se de que o nome esteja definido como "SentimentDemo" e escolha Criar conector.

Examinar e atualizar a definição de conector

O assistente de conector personalizado fornece muitas opções para definir o funcionamento do conector e como ele é exposto em Aplicativos Lógicos, fluxos e aplicativos. Explicaremos a interface do usuário e abordaremos algumas opções nesta seção, mas também incentivamos você a explorar por conta própria.

Revisar a interface do usuário e a definição

Antes de entrarmos em algumas etapas específicas na página Definição , vamos primeiro dar uma olhada na IU.

1. Esta área exibe as ações, os gatilhos (para os Aplicativos Lógicos e o Power Automate) e as referências que são definidas para o conector. Neste caso, a DetectSentiment ação da coleção Postman é exibida. Não há gatilhos neste conector, mas você pode aprender sobre gatilhos para conectores personalizados em Usar webhooks com o Azure Logic Apps e Power Automate.

   

2. A área Geral exibe informações sobre a ação ou o gatilho selecionado no momento. Essas informações são provenientes da coleção do Postman. Você pode editar as informações aqui, incluindo a propriedade Visibilidade para operações e parâmetros em um aplicativo lógico ou fluxo:

   • importante: sempre mostrado primeiro ao usuário
   • none: exibido normalmente no aplicativo lógico ou fluxo
   • avançado: inicialmente oculto em um menu adicional
   • interno: não mostrado ao usuário

3. A área Solicitação exibe informações com base na solicitação HTTP incluída na coleção Postman. Nesse caso, você vê que o verbo HTTP é POST , e a URL é "/text/analytics/v2.0/sentiment" (a URL completa para a API é). <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment> Analisaremos mais detalhadamente o parâmetro body em breve.

4. A área Resposta exibe informações com base na resposta HTTP incluída na coleção Postman. Nesse caso, a única resposta definida é "200" (uma resposta bem-sucedida), mas é possível definir respostas adicionais.

5. A área Validação exibe problemas detectados na definição da API. Verifique essa área antes de salvar um conector.

Atualizar a definição

Agora vamos alterar algumas coisas para que o conector fique mais amigável quando alguém o usa em um Aplicativo Lógico, Power Automate ou Power Apps.

1. Na área Geral, atualize o resumo para "Retorna uma pontuação numérica que representa o sentimento detectado".

2. Na área Solicitação , escolha corpo e Editar.

3. Na área Parâmetro , agora você vê os três parâmetros que a API espera: id, language e text. Escolha id e Editar.

4. Na área Propriedade do esquema , atualize os valores do parâmetro e escolha Voltar.

   

   Parâmetro	Valor
   Title	"ID"
   Descrição	"Um identificador para cada documento que você enviar"
   Valor padrão	"1"
   É necessário	"Sim"

5. Na área Parâmetros , escolha idioma , depois Editar e repita o processo usado acima com os seguintes valores.

   Parâmetro	Valor
   Title	"Linguagem"
   Descrição	"O código de idioma de 2 ou 4 caracteres para o texto"
   Valor padrão	"en"
   É necessário	"Sim"

6. Na área Parâmetro , escolha texto , depois Editar e repita o processo usado acima com os seguintes valores.

   Parâmetro	Valor
   Title	"Texto"
   Descrição	"O texto no qual analisar o sentimento"
   Valor padrão	Nenhum(a)
   É necessário	"Sim"

7. Na área Parâmetro, escolha Voltar para voltar à página principal de definição.

8. No canto superior direito do assistente, escolha Atualizar conector.

Testar o conector

Após criar o conector, teste-o para verificar se ele está funcionando corretamente. Atualmente, os testes estão disponíveis somente no Power Automate e no Power Apps.

Importante

Ao usar uma chave de API, recomendamos não testar o conector imediatamente após a criação. Pode levar alguns minutos até que o conector esteja pronto para se conectar à API.

1. Na página Teste, escolha Nova conexão.

2. Insira a chave de API da API do Text Analytics e escolha Criar conexão.

3. Retornar para a Página de teste:

   • Em Power Automate, você será levado de volta para a página Teste . Escolha o ícone de atualização para fazer com que as informações de conexão sejam atualizadas.
   • No Power Apps, você será direcionado para a lista de conexões disponíveis no ambiente atual. No canto superior direito, escolha o ícone de engrenagem e depois escolha Conectores personalizados. Escolha o conector que você criou e volte para a página Teste .

4. Na página Teste , insira um valor para o campo texto (os outros campos usam os padrões definidos anteriormente) e escolha Operação de teste.

5. O conector chamará a API e você poderá analisar a resposta, que inclui a pontuação de sentimento.

   

Limitações

No Power Automate e no Power Apps, se você atualizar um conector personalizado usando uma coleção Postman, precisará refazer todas as personalizações anteriores antes de salvar o conector. Por exemplo, será necessário reconfigurar o tipo de autenticação, os valores padrão dos parâmetros para as ações, entre outros.

Próximas etapas

Agora que você criou um conector personalizado e definiu os comportamentos, poderá usar o conector.

• Use um conector personalizado de um fluxo
• Use um conector personalizado de um aplicativo
• Use um conector personalizado de um aplicativo lógico

Também é possível compartilhar o conector em sua organização e/ou obter a certificação do conector para que as pessoas fora de sua organização possam usá-lo.

• Compartilhe seu conector
• Certifique seu conector

Faça comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer feedback, acesse Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.