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

Para criar um conector personalizado, descreva a API à qual você deseja se conectar para que o conector compreenda as ações e as estruturas de dados da API. Neste artigo, irá criar um conector personalizado usando uma coleção Postman que descreve a API de Análise de Sentimentos da Análise de Texto dos Cognitive Services (o 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 OpenAPI definição

• Criar um conector personalizado a partir do zero

Pré-requisitos

Verifique os pré-requisitos para se certificar de que tem tudo o que precisa para criar um conector personalizado. Necessita de:

• Uma coleção Postman que descreve a API de exemplo. Siga as orientações em Criar uma coleção Postman para um conector personalizado.

• 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 Aplicações Lógicas
  • Power Automate
  • Aplicações Power

• Se você estiver a usar Aplicativos Lógicos, primeiro crie um conector personalizado de Aplicativos Lógicos do Azure.

Importar a coleção do Postman

Agora você está pronto para usar a coleção Postman que você criou ou baixou. A coleção tem muitas das informações necessárias. Você pode revisar e atualizar essas informações à medida que passa pelo assistente de conector personalizado. Comece importando a coleção Postman para Aplicativos Lógicos ou para Power Automate e Power Apps.

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

1. Vá para o portal doAzure e abra o conector de Aplicativos Lógicos que você criou anteriormente em Criar um conector personalizado de Aplicativos Lógicos do Azure.

2. No menu do conector, escolha Logic Apps Connector (Conector de aplicativos lógicos) 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, em seguida, converte-a em uma OpenAPI definição nomeada generatedApiDefinition.swagger.json.

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

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

2. No painel de navegação, selecione Mais>Descobrir tudo

3. Na seção Dados, selecione Conectores personalizados.

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

5. 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 definição OpenAPI chamada generatedApiDefinition.swagger.json.

Atualizar os detalhes gerais

A partir deste ponto, este artigo mostra a interface do usuário do Power Automatic, mas as etapas são basicamente as mesmas em todas as três tecnologias. As diferenças são destacadas conforme necessário.

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 utiliza o anfitrião e o URL de base da API para determinar como a chamar.

   Nota

   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 com algo significativo. Essa descrição aparece nos detalhes do conector personalizado e ajuda outros usuários a entender como o conector é ú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

Os conectores personalizados suportam várias opções de autenticação. 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 um rótulo de parâmetro, nome e local. 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
   Rótulo 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, verifique se o nome está definido como "SentimentDemo" e escolha Criar conector.

Rever e atualizar a definição do conector

O assistente de conector personalizado oferece muitas opções para definir como o conector funciona e como ele é exposto em aplicativos lógicos, fluxos, aplicativos e agentes. Esta seção explica a interface do usuário e aborda algumas opções, mas você pode explorar mais por conta própria.

Rever a IU e a definição

Antes de seguir as etapas na página Definição , revise a interface do usuário.

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

   

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

   • Importante: Sempre mostrado ao utilizador primeiro
   • nenhum: exibido normalmente no aplicativo lógico ou fluxo
   • Avançado: Inicialmente oculto sob um menu adicional
   • interna: não mostrada ao utilizador

3. A área Request exibe informações com base na solicitação HTTP incluída na coleção Postman. Nesse caso, você verá 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>). Você vai analisar mais detalhadamente o body parameter em breve.

4. A área Response exibe informações com base na resposta HTTP incluída na coleção Postman. Neste caso, a única resposta definida é para “200” (uma resposta de êxito), mas pode definir respostas adicionais.

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

Atualizar a definição

Agora, altere algumas configurações para tornar o conector mais fácil de usar em um Logic App, no Power Automate ou no Power Apps.

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

2. Na área Solicitação , escolha corpo e depois 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, em seguida, Editar.

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

   

   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 e, em seguida , Editar e repita o processo usado acima com os seguintes valores.

   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 e, em seguida , Editar e repita o processo usado acima com os seguintes valores.

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

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

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

Testar o conector

Depois de criar o conector, teste-o para verificar se ele funciona corretamente. Os testes estão disponíveis apenas em Power Automate e Power Apps.

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

2. Insira a chave da API da API de Análise de Texto e escolha Criar conexão.

3. Regressar à página Teste:

   • Em Power Automate, você é levado de volta 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, escolha o ícone de engrenagem e, em seguida, 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 de texto (os outros campos usam os padrões definidos anteriormente) e escolha Operação de teste.

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

   

Limitações

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

Próximos passos

Depois de criar um conector personalizado e definir os seus comportamentos, use o conector.

• Usar um conector personalizado a partir de um fluxo
• Usar um conector personalizado de um aplicativo
• Usar um conector personalizado de um aplicativo lógico

Você também pode compartilhar um conector dentro da sua organização ou obter a certificação do conector para que pessoas fora da sua organização possam usá-lo.

• Partilhe o seu conector
• Certificar o seu conector

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.