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

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 maneira de descrever uma API, vá para Criar um conector personalizado do zero.

Pré-requisitos

• Uma definição de OpenAPI (OAD) 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 precisa 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, aplicativo e senha) na OAuth definição de segurança.

• 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 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 importando a OpenAPI definição para Aplicativos Lógicos ou para Power Automate e Power Apps.

Importar a definição de OpenAPI para 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, selecione Conector de aplicativos lógicos e, em seguida, selecione Editar.

   

3. Em Geral, selecione Carregar um OpenAPI ficheiro e, em seguida, aceda à OpenAPI definição que criou.

   

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, selecione Conectores> personalizados de dados.

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

4. Insira um nome para o conector personalizado, vá para a OpenAPI definição que você baixou 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, verifique se o nome está definido como SentimentDemo e selecione Criar conector.

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

   

   Nota

   Para obter mais informações sobre como se conectar a APIs locais, vá para Conectar a APIs locais usando 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 , revise as informações de autenticação da chave da API.

O rótulo é exibido quando alguém faz uma conexão pela primeira vez com o conector personalizado; você pode selecionar Editar e alterar esse valor. O nome e o local do parâmetro devem 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 de conector personalizado oferece muitas opções para definir como o conector funciona e como ele é exposto em aplicativos lógicos, fluxos e aplicativos. 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 como definir objetos do zero nesta interface do utilizador, vá para Criar a definição de 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. Nesse caso, a DetectSentiment OpenAPI ação da definição é 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. Você pode editar as informações aqui, incluindo a propriedade Visibility para operações e parâmetros em um aplicativo lógico ou fluxo:

   • nenhum: exibido normalmente no aplicativo lógico ou fluxo

   • Avançado: oculto sob um menu adicional

   • interna: oculta do utilizador

   • Importante: Sempre mostrado ao utilizador primeiro

     

3. A área Solicitação exibe informações com base na solicitação HTTP incluída na OpenAPI definição. Nesse caso, você verá 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>). Veremos mais de perto o parâmetro corporal em breve.

   

   A secção a seguir da OpenAPI definição contém informações para as áreas Geral e Solicitação da interface do utilizador:

   "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 exibe informações com base na resposta HTTP incluída na OpenAPI definição. Nesse caso, a única resposta definida é para 200 (uma resposta bem-sucedida), mas você 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 que são retornados pelo conector: id and score. Inclui os seus tipos de dados e o campo x-ms-summary, que é uma OpenAPI extensão. Para obter mais informações sobre essa e outras extensões, vá para Estender uma OpenAPI definição para um conector personalizado.

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

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 , agora você vê 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 Voltar.

   

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

4. Na área Parâmetro, selecione Voltar para voltar à 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.

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

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

3. Volte à página Teste e siga um destes procedimentos:

   • 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, selecione o ícone de engrenagem e, em seguida, selecione 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 selecione Operação de teste.

   

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

   

Usar o conector personalizado

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

• Use um conector personalizado em Power Automate
• Use um conector personalizado em Power Apps
• Usar um conector personalizado em um Logic Apps
• Use uma ação personalizada de conector e conector em Copilot Studio

Criar uma ação personalizada de conector e conector para Microsoft 365 o Copilot for Sales

Você pode criar um conector personalizado a partir de uma OpenAPI definição ou Power Apps Power Automate que pode ser usado para Microsoft 365 o Copilot for Sales. Vá para Criar um conector personalizado e uma ação de conector para saber como começar.

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

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