Criar um conector personalizado de uma coleção Postman

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ê criará um conector personalizado usando uma coleção Postman que descreve a API de Sentimento da Análise de Texto dos Serviços Cognitivos (nosso exemplo para esta série).

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

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

• Criar um conector personalizado do zero

Pré-requisitos

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

  • Baixe a coleção Postman criada
    ou
  • Conclua o tópico Criar uma coleção Postman para um conector personalizado Observe que, ao criar um conector personalizado, a coleção Postman deve ter menos de 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 Aplicativos Lógicos do Azure.
  • Power Automate
  • Power Apps

• Caso esteja usando Aplicativos Lógicos, primeiro crie um conector personalizado dos Aplicativos Lógicos do Azure

Importar a coleção Postman

Agora você está pronto para trabalhar com a coleção Postman criada ou baixada. 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 os Aplicativos Lógicos ou para o Power Automate e o Power Apps.

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

1. Acesse o portal do Azure e abra o conector dos Aplicativos Lógicos que você criou anteriormente em Criar um conector personalizado dos Aplicativos Lógicos do Azure.

2. No menu do conector, escolha Conector de Aplicativos Lógicos e escolha Editar.

   

3. Em Geral, escolha Carregar coleção Postman V1 e navegue até a coleção Postman criada.

   

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

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 Importar uma coleção Postman.

4. Insira um nome para o conector personalizado, navegue para a coleção Postman baixada ou criada 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 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, analise as informações que foram importadas da coleção Postman, inclusive 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 a conexão 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"
   Local de parâmetro	"Cabeçalho"

3. Na parte superior do assistente, verifique se o nome está definido como "SentimentDemo" e selecione 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 examinar a interface do usuário.

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 ação DetectSentiment da coleção Postman é exibida. Não há nenhum gatilho nesse conector, mas você pode aprender sobre gatilhos para conectores personalizados em Usar webhooks com os Aplicativos Lógicos do Azure e o 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. É possível editar as informações aqui, incluindo a propriedade Visibilidade para operações e parâmetros em um aplicativo lógico ou um fluxo:

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

3. A área Solicitação exibe informações com base na solicitação HTTP que está incluída na coleção Postman. Neste 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>). Examinaremos mais detalhadamente o parâmetro corpo em breve.

4. A área Resposta exibe informações com base na resposta HTTP que está 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, você vê os três parâmetros esperados pela API: id, language e text. Escolha id e Editar.

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

   

   Parâmetro	Valor
   Título	"ID"
   Descrição	"Um identificador para cada documento que você enviar"
   Valor padrão	"1"
   É obrigatório	"Sim"

5. Na área Parâmetro, escolha linguagem, Editar e repita o processo usado acima nos valores a seguir.

   Parâmetro	Valor
   Título	"Linguagem"
   Descrição	"O código de idioma de 2 ou 4 caracteres para o texto"
   Valor padrão	"en"
   É obrigatório	"Sim"

6. Na área Parâmetro, escolha texto, Editar e repita o processo usado acima nos valores a seguir.

   Parâmetro	Valor
   Título	"Texto"
   Descrição	"O texto no qual analisar o sentimento"
   Valor padrão	Nenhum(a)
   É obrigatório	"Sim"

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

8. Na parte superior direita do assistente, escolha Atualizar conector.

Testar o conector

Agora que você criou 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.

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

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

3. Volte para a página Teste:

   • No Power Automate, você será redirecionado 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 escolha Conectores personalizados. Escolha o conector criado e volte para a página Teste.

4. Na página Teste, insira um valor no campo texto (os outros campos usam os padrões que você definiu anteriormente) e escolha Testar operação.

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.

• Usar um conector personalizado de um fluxo
• Usar um conector personalizado de um aplicativo
• Usar 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.

• Compartilhar seu conector
• Certificar seu conector

Enviar comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.