Criar um conector personalizado a partir de uma coleção do Postman

Para criar um conector personalizado, tem de descrever a API à qual se pretende ligar, para que o conector compreenda as operações e as estruturas de dados da API. Neste tópico, crie um conector personalizado com uma Coleção do Postman que descreva a API de Sentimento de Análise de Texto dos Serviços Cognitivos (o nosso exemplo para esta série).

Para outras formas de descrever uma API, aceda aos seguintes tópicos:

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

• Criar um conector personalizado do zero

Pré-requisitos

• Uma coleção do Postman que descreve a API de exemplo:

  • Transferir a coleção do Postman que criámos
    ou
  • Conclua o tópico Criar uma coleção do Postman para um conector personalizado Tenha em conta que, ao criar um conector personalizado, a coleção do Postman tem de ser inferior a 1 MB.

• Uma chave de API para a API de Análise de Texto dos Serviços Cognitivos

• Uma das seguintes subscrições:

  • Azure, se estiver a utilizar o Logic Apps
  • Power Automate
  • Power Apps

• Se estiver a utilizar o Logic Apps, comece por criar um conector personalizado do Azure Logic Apps

Importar a coleção do Postman

Está agora pronto para trabalhar com a coleção do Postman que criou ou transferiu. Muitas das informações necessárias estão presentes na coleção. Também pode rever e atualizar essas informações à medida que avança no assistente do conector personalizado. Comece por importar a coleção do Postman para o Logic Apps ou para o Power Automate e Power Apps.

Importar a coleção do Postman para o Logic Apps

1. Aceda ao portal do Azure e abra o conector do Logic Apps que criou anteriormente em Criar um conector personalizado do Azure Logic Apps.

2. No menu do conector, escolha Conector do Logic Apps e depois escolha Editar.

   

3. Em Geral, escolha Carregar uma Coleção do Postman V1 e navegue para a coleção do Postman que criou.

   

   O assistente importa a coleção e, em seguida, converte-a numa definição de OpenAPI denominada generatedApiDefinition.swagger.json.

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

1. Vá a make.powerapps.com ou flow.microsoft.com.

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

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

4. Introduza um nome para o conector personalizado, navegue até à coleção do Postman que transferiu ou criou e escolha Continuar.

   

   Parâmetro	valor
   Título do conector personalizado	“SentimentDemo”

   O assistente importa a coleção e, em seguida, converte-a numa definição de OpenAPI denominada generatedApiDefinition.swagger.json.

Atualizar os detalhes gerais

A partir deste ponto, mostraremos a IU do Power Automate, mas os passos são praticamente os mesmos nas três tecnologias. Destacaremos as diferenças.

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

   Nota

   Para mais informações sobre como ligar a APIs no local, consulte Ligar a APIs no local utilizando o gateway de dados.

2. Atualize a descrição com algo significativo. Esta descrição é apresentada nos detalhes do conector personalizado e pode ajudar outros utilizadores a saber se o conector lhes pode ser útil.

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

Especificar o tipo de autenticação

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

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

2. Em Chave de API, especifique uma etiqueta de parâmetro, um nome e uma localização. Escolha uma etiqueta descritiva e relevante. Este texto será apresentado aos utilizadores para os orientar para fazerem ligações com o seu conector personalizado. O nome e a localização do parâmetro têm de corresponder ao que a API espera (neste caso, o cabeçalho que especificou no Postman). Escolha Ligar.

   

   Parâmetro	valor
   Etiqueta do 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 está definido como "SentimentDemo" e, em seguida, selecione Criar conector.

Rever e atualizar a definição do conector

O assistente do conector personalizado dá-lhe muitas opções para definir como funciona o conector e como está exposto mas aplicações lógicas, nos fluxos e nas aplicações. Explicaremos a IU e abordaremos algumas opções nesta secção, mas também encorajamos que explore por conta própria.

Rever a IU e a definição

Antes de chegarmos a alguns passos específicos na página Definição, primeiro vamos analisar a IU.

1. Esta área apresenta todas as ações, acionadores (para o Logic Apps e o Power Automate) e referências que estão definidos para o conector. Neste caso, é apresentada a ação DetectSentiment da coleção do Postman. Este conector não tem acionadores, mas pode saber mais sobre os acionadores para os conectores personalizados em Utilizar webhooks com o Azure Logic Apps e o Power Automate.

   

2. A área Geral apresenta informações sobre a ação ou o acionador atualmente selecionado. Estas informações provêm da coleção do Postman. Pode editar as informações aqui, incluindo a propriedade Visibilidade das operações e dos parâmetros em aplicações lógicas ou em fluxos:

   • importante: sempre mostrada primeiro ao utilizador
   • nenhum: apresentado normalmente na aplicação lógica ou no fluxo
   • avançada: inicialmente ocultada num menu adicional
   • interna: não é apresentada ao utilizador

3. A área Pedido apresenta informações baseadas no pedido HTTP que estão incluídas na coleção do Postman. Neste caso, vê que o verbo HTTP é POST e o URL é "/text/analytics/v2.0/sentiment" (o URL completo para a API é <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Vamos analisar melhor o parâmetro body mais à frente.

4. A área Resposta apresenta informações baseadas na resposta HTTP que estão incluídas na coleção do Postman. Neste caso, a única resposta definida é para “200” (uma resposta de êxito), mas pode definir respostas adicionais.

5. A área Validação mostra todos os problemas detetados na definição da API. Confirme que a verifica antes de guardar um conector.

Atualizar a definição

Agora, vamos alterar algumas coisas, para que o conector seja mais amigável quando alguém o utilizar numa aplicação Logic Apps, Power Automate ou Power Apps.

1. Na área Geral, atualize o resumo para "Devolve uma classificação numérica que representa um sentimento detetado".

2. Na área Pedido, escolha corpo e, em seguida, Editar.

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

4. Na área Propriedade do Esquema, atualize os valores do parâmetro e selecione Anterior.

   

   Parâmetro	valor
   Cargo	"ID"
   Descrição	"Um identificador para cada documento que submeter"
   Valor predefinido	"1"
   É obrigatório	"Sim"

5. Na área Parâmetro, escolha idioma, Editar e repita o processo que utilizou acima, com os valores seguintes.

   Parâmetro	valor
   Cargo	"Idioma"
   Descrição	"O código de idioma de 2 ou 4 carateres do texto"
   Valor predefinido	"en"
   É obrigatório	"Sim"

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

   Parâmetro	valor
   Cargo	"Texto"
   Descrição	"O texto para analisar quanto a sentimento"
   Valor predefinido	Nenhuma
   É obrigatório	"Sim"

7. Na área Pârametro, escolha Anterior para regressar à página de definição principal.

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

Testar o conector

Agora que criou o conector, teste-o para se certificar de que está a funcionar corretamente. Os testes estão atualmente disponíveis apenas no Power Automate e no Power Apps.

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

2. Introduza a chave da API de Análise de Texto e, em seguida, escolha Criar ligação.

3. Volte à página de Teste:

   • No Power Automate, é direcionado novamente para a página Teste. Selecione o ícone de atualização para confirmar que as informações da ligação são atualizadas.
   • No Power Apps, é direcionado para a lista de ligações disponíveis no ambiente atual. No canto superior direito, selecione o ícone de engrenagem e, em seguida, Conectores personalizados. Escolha o conector que criou e regresse à Página de teste.

4. Na página Teste, introduza um valor no campo texto (os outros campos utilizam as predefinições que definiu anteriormente) e selecione Operação de teste.

5. O conector chama a API e poderá rever a resposta, que inclui a classificação de sentimento.

   

Limitações

No Power Automate e no Power Apps, se atualizar um conector personalizado existente utilizando uma coleção do Postman, terá de voltar a efetuar quaisquer personalizações antes de guardar o conector. Por exemplo, precisará de voltar a configurar o tipo de autenticação, os valores predefinidos dos parâmetros para as ações, entre outros.

Próximos passos

Agora que criou um conector personalizado e definiu os comportamentos do mesmo, pode utilizá-lo.

• Utilizar um conector personalizado a partir de um fluxo
• Utilizar um conector personalizado a partir de uma aplicação
• Utilizar um conector personalizado a partir de uma aplicação lógica

Também pode partilhar conectores dentro da sua organização e/ou certificá-los, para que possam ser utilizados por pessoas externas à sua organização.

• Partilhar o conector
• Certificar o conector

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.