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

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, Microsoft Power Automate e Microsoft 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 utilizando uma definição de OpenAPI que descreva a API de Sentimento de Análise de Texto de Serviços Cognitivos (o nosso exemplo para esta série).

Para outra forma de descrever uma API, aceda a Criar um conector personalizado a partir do zero.

Pré-requisitos

• Uma definição de OpenAPI que descreve a API de exemplo. Ao criar um conector personalizado, a definição de OpenAPI tem de ser inferior a 1 MB. A definição de OpenAPI necessita de estar no formato OpenAPI 2.0 (anteriormente conhecido como Swagger).

  Se existirem várias definições de segurança, o conector personalizado selecionará a definição de segurança principal. A criação de conector personalizado não suporta credenciais de cliente (por exemplo, aplicação e palavra-passe) na definição de segurança OAuth.

• 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 definição de OpenAPI

Agora, está pronto para trabalhar com a definição de OpenAPI que transferiu. Toda a informação necessária está contida na definição. Poderá rever e atualizar esta informação à medida que avança no assistente do conector personalizado.

Comece por importar a definição de OpenAPI para Logic Apps ou para Power Automate e Power Apps.

Nota

Uma definição de OpenAPI necessita de estar no formato OpenAPI 2.0 (anteriormente conhecido como Swagger). As definições de OpenAPI que estão no formato OpenAPI 3.0 não são suportadas.

Importar a definição de OpenAPI para 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, selecione Conector do Logic Apps e depois selecione Editar.

   

3. Em Geral, selecione Carregar um ficheiro OpenAPI e, em seguida, vá para a definição de OpenAPI que criou.

   

Nota

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

Importar a definição de OpenAPI para Power Automate e Power Apps

1. Iniciar sessão no Power Apps ou no Power Automate.

2. No painel esquerdo, selecionar Dados > Conectores personalizados.

   

3. Selecione Novo conector personalizado e, em seguida, selecione Importar um ficheiro OpenAPI.

   

4. Introduza um nome para o conector personalizado, vá para a definição de OpenAPI que transferiu ou criou e selecione Continuar.

   

   Parâmetro	valor
   Título do conector personalizado	SentimentDemo

Rever detalhes gerais

A partir deste ponto, vamos mostrar a IU do Power Automate, mas os passos são praticamente os mesmos nas três tecnologias. Vamos mostrar as diferenças. Nesta parte do tópico, iremos rever sobretudo a IU e mostrar como os valores correspondem a secções do ficheiro OpenAPI.

1. Na parte superior do assistente, certifique-se de que o nome está definido como SentimentDemo e, em seguida, selecione Criar conector.

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

   

   Nota

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

   A secção seguinte da definição de OpenAPI contém informações para esta página da IU:

     "info": {
       "version": "1.0.0",
       "title": "SentimentDemo",
       "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
     },
     "host": "westus.api.cognitive.microsoft.com",
     "basePath": "/",
     "schemes": [
       "https"
     ]
   

Rever tipo de autenticação

Existem várias opções disponíveis para a autenticação nos conectores personalizados. As APIs Serviços Cognitivos utilizam autenticação de chave de API, por isso é o que está especificado na definição de OpenAPI.

Na página Segurança, reveja as informações de autenticação para a chave de API.

A etiqueta é apresentada quando alguém estabelece uma primeira ligação com o conector personalizado; pode selecionar Editar e alterar este valor. O nome e a localização do parâmetro têm de corresponder ao que a API espera, neste caso Ocp-Apim-Subscription-Key e Header.

A secção seguinte da definição de OpenAPI contém informações para esta página da IU:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Rever a definição do conector

A página Definição do assistente do conector personalizado oferece muitas opções para definir o funcionamento do conector e a forma como é exposto em aplicações lógicas, fluxos e aplicações. Explicaremos a IU e abordaremos algumas opções nesta secção, mas também encorajamos que explore por conta própria. Para obter informações sobre a definição de objetos do zero, vá para Criar a definição do conector.

1. A área seguinte 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 definição de OpenAPI. 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. 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:

   • nenhum: apresentado normalmente na aplicação lógica ou no fluxo

   • avançada: ocultada num menu adicional

   • interna: ocultada do utilizador

   • importante: sempre mostrada primeiro ao utilizador

     

3. A área Pedido apresenta informações com base no pedido HTTP incluído na definição de OpenAPI. 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.

   

   A secção seguinte da definição de OpenAPI contém informações para as áreas Geral e Pedido da IU:

   "paths": {
     "/text/analytics/v2.0/sentiment": {
       "post": {
         "summary": "Returns a numeric score representing the sentiment detected",
         "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
         "operationId": "DetectSentiment"
   

4. A área Resposta apresenta informações com base na resposta HTTP incluído na definição de OpenAPI. Neste caso, a única resposta definida é para 200 (uma resposta de êxito), mas pode definir respostas adicionais.

   

   A secção seguinte da definição de OpenAPI contém algumas das informações relacionadas com a resposta:

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   Esta secção mostra os dois valores devolvidos pelo conector: id e score. Inclui os respetivos tipos de dados e o campo x-ms-summary, que é uma extensão OpenAPI. Para obter mais informações sobre esta e outras extensões, vá para Expandir uma definição de OpenAPI para um conector personalizado.

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

A definição de OpenAPI que transferiu é um bom exemplo básico, mas poderá trabalhar com definições que precisam de muitas atualizações para que o conector seja mais amigável quando alguém o utilizar numa aplicação lógica, num fluxo ou numa aplicação. Mostraremos como efetuar uma alteração à definição.

1. Na área Pedido, selecione corpo e, em seguida, selecione Editar.

   

2. Na área Parâmetro, vê agora os três parâmetros que a API espera: ID, Language e Text. Selecione ID e, em seguida, selecione Editar.

   

3. Na área Propriedade do Esquema, atualize a descrição do parâmetro e selecione Anterior.

   

   Parâmetro	valor
   Descrição	Um identificador numérico para cada documento que submeter

4. Na área Parâmetro, selecione Anterior para regressar à página de definição principal.

5. No canto superior direito do assistente, selecione Atualizar conector.

Transferir o ficheiro OpenAPI atualizado

Pode criar um conector personalizado a partir de um ficheiro OpenAPI ou do zero (no Power Automate e Power Apps). Independentemente de como criar o conector, pode transferir a definição OpenAPI que o serviço utiliza internamente.

• No Logic Apps, transfira a partir do conector personalizado.

  

• No Power Automate ou no Power Apps, transfira o a partir da lista de conectores personalizados.

  

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 Testar, selecione Nova ligação.

   

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

   

3. Regresse ao separador Testar página e faça uma das seguintes ações:

   • 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 selecione Conectores personalizados. Escolha o conector que criou e regresse à página Testar.

     

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.

   

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 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.