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, cria um conector personalizado com base numa definição OpenAPI que descreve a API de Análise de Sentimento do Análise de Texto dos Serviços Cognitivos (o nosso exemplo nesta 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 conectores personalizados não suporta as credenciais do 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 Logic Apps
  • Power Automate
  • Power Apps

• 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

Este tutorial utiliza um exemplo de definição OpenAPI para a API Cognitive Services Análise de Texto Sentiment. Para acompanhar, crie um ficheiro JSON local com o nome SentimentDemo.json e cole na seguinte definição do OpenAPI 2.0:

{
  "swagger": "2.0",
  "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"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "security": [{"api_key": []}],
  "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",
        "parameters": [{
          "in": "body",
          "name": "body",
          "schema": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string", "x-ms-summary": "id"},
                    "language": {"type": "string", "x-ms-summary": "language"},
                    "text": {"type": "string", "x-ms-summary": "text"}
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "documents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "score": {"type": "number", "format": "float", "description": "score", "x-ms-summary": "score"},
                      "id": {"type": "string", "description": "id", "x-ms-summary": "id"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Agora está pronto para importar esta definição da OpenAPI. A definição contém toda a informação necessária. Você pode revisar e atualizar essas informações à medida que passa pelo assistente de 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, seleciona Soluções, depois abre a solução que queres usar, ou cria uma nova.

3. Selecione Novo>Automação>Conector personalizado.

4. Selecione Importar um ficheiro OpenAPI.

5. Introduza um nome para o conector personalizado, selecione o SentimentDemo.json ficheiro que criou e depois selecione Continuar.

   

   Parâmetro	valor
   Título do conector personalizado	SentimentDemo

Ver 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 ligar a APIs no local, consulte Ligar a APIs no local com 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 dos Serviços Cognitivos utilizam autenticação com chave de API, pelo que é isso que está especificado na definição 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 criar objetos de raiz nesta interface de utilizador, consulte 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, é exibida a ação DetectSentiment da definição OpenAPI. Não existem acionadores neste conector, mas pode obter mais informações sobre acionadores para conectores personalizados em Utilizar webhooks com Azure Logic Apps e Power Automate.

   

2. A área Geral exibe informações sobre a ação ou gatilho selecionado no momento. Pode editar aqui as informações, incluindo a propriedade Visibilidade das operações e dos parâmetros numa aplicação lógica ou fluxo:

   • nenhum: exibido normalmente na aplicação lógica ou no 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>). Analisaremos mais detalhadamente o parâmetro body mais adiante.

   

   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. Certifique-se de verificar esta área 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, em seguida, 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 da forma 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 a partir da lista de conectores personalizados.

  

Teste 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 execute uma das seguintes ações:

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

• Utilizar um conector personalizado no Power Automate
• Utilize um conector personalizado no Power Apps
• Usar um conector personalizado numa aplicação Logic Apps
• Utilize um conector personalizado e uma ação do conector no Copilot Studio

Criar um conector personalizado e uma ação de conector para o Microsoft 365 Copilot para Vendas

Pode criar um conector personalizado a partir de uma definição OpenAPI no Power Apps ou no Power Automate, que pode depois ser utilizado para o Microsoft 365 Copilot para Vendas. Aceda a 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.