Partilhar via

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

  • Artigo

Nota

Este tópico faz parte de uma série de tutoriais sobre a criação e a utilização de conectores personalizados no Azure Logic Apps, Power Automate e Power Apps. Certifique-se de que leu a descrição geral do conector personalizado para compreender o processo.

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:

Pré-requisitos

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.

    Editar Conector do Logic Apps

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

    Captura de ecrã que mostra a opção Carregar uma Coleção do Postman V1.

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

Nota

Este tutorial concentra-se numa API REST, mas também pode utilizar uma API SOAP com o Logic Apps.

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.

    Captura de ecrã que mostra os passos para importar a coleção.

    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âmetros da chave de API

    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.

    Página de definição - ações e acionadores

  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.

    Editar propriedade do esquema

    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.

Importante

Quando utiliza uma chave de API, recomendamos não testar o conector imediatamente depois de o criar. Pode demorar alguns minutos até o conector estar pronto para ligar à API.

  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.

    Resposta do conector

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.

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.

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.