Criar um conector personalizado de uma definição OpenAPI

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

Para ver outra maneira de descrever uma API, acesse Criar um conector personalizado do zero..

Pré-requisitos

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

  Se houver várias definições de segurança, o conector personalizado escolherá a primeira definição de segurança. A criação de conector personalizado não oferece suporte a credenciais de cliente (por exemplo, aplicativo e senha) na definição de segurança do OAuth.

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

Agora você está pronto para trabalhar com a definição OpenAPI baixada. Todas as informações necessárias estão contidas na definição e você pode revisar e atualizar essas informações à medida que avança no assistente de conector personalizado.

Comece importando a definição OpenAPI para Aplicativos Lógicos ou para Power Automate e Power Apps.

Importar a definição OpenAPI para Aplicativos Lógicos

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

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

   

3. Em Geral, selecione Carregar um arquivo OpenAPI e acesse a definição OpenAPI que você criou.

   

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

1. Entre no Power Apps ou Power Automate.

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

   

3. Selecione Novo conector personalizado e, depois, Importar um arquivo OpenAPI.

   

4. Insira um nome para o conector personalizado, acesse a definição OpenAPI baixada ou criada e, depois, selecione Continuar.

   

   Parâmetro	Valor
   Título do conector personalizado	SentimentDemo

Revisar detalhes gerais

A partir desse ponto, será exibida a interface do usuário do Power Automate, mas as etapas são basicamente as mesmas nas três tecnologias. Apontaremos quaisquer diferenças. Nesta parte do tópico, revisaremos principalmente a interface do usuário e mostraremos como os valores correspondem às seções do arquivo OpenAPI.

1. Na parte superior do assistente, verifique se o nome está definido como SentimentDemo e, depois, selecione Criar conector.

2. Na página Geral, examine as informações importadas da definição OpenAPI, inclusive o host da API e a URL base da API. O conector usa o host da API e a URL base para determinar como chamar a API.

   

   Observação

   Para obter mais informações sobre a conexão a APIs locais, vá para Conectar-se a APIs locais usando o gateway de dados.

   A seguinte seção da definição OpenAPI contém informações para esta página da interface do usuário:

     "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"
     ]
   

Revisar 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 autenticação de chave de API, o que é especificado na definição OpenAPI.

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

O rótulo é exibido quando alguém faz uma conexão 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; nesse caso, Ocp-Apim-Subscription-Key e Cabeçalho.

A seguinte seção da definição OpenAPI contém informações para esta página da interface do usuário:

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

Revisar a definição do conector

A página Definição do assistente de conector personalizado oferece várias opções para definir como o conector funciona 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. Para obter informações sobre como definir objetos do zero nesta interface do usuário, acesse Criar a definição de conector.

1. A área a seguir 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 definição OpenAPI é exibida. Não há gatilho nesse conector, mas você pode aprender sobre gatilhos para conectores personalizados em Usar webhooks com 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. É 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:

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

   • avançado: oculto em um menu adicional

   • interno: ocultado do usuário

   • importante: sempre exibido para o usuário primeiro

     

3. A área Solicitação exibe informações com base na solicitação HTTP que está incluída na definição OpenAPI. Neste caso, você vê que o verbo HTTP é POST e a URL é /text/analytics/v2.0/sentiment (a URL completa da API é <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Examinaremos detalhadamente o parâmetro corpo em breve.

   

   A seção seguinte da definição OpenAPI contém informações para as áreas Geral e Solicitação da interface do usuário:

   "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 que está incluída na definição OpenAPI. Nesse caso, a única resposta definida é 200 (uma resposta bem-sucedida), mas é possível definir respostas adicionais.

   

   A seção seguinte da definição OpenAPI contém algumas das informações relacionadas à resposta:

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

   Esta seção mostra os dois valores retornados pelo conector: id e score. Isso inclui seus 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, acesse Estender uma definição OpenAPI para um conector personalizado.

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

A definição de OpenAPI baixada é um bom exemplo básico, mas você pode vir a trabalhar com definições que exigem muita atualização para que o conector fique mais fácil de usar quando alguém for usá-lo em um aplicativo lógico, em um fluxo ou em um aplicativo. Mostraremos como fazer uma alteração na definição.

1. Na área Solicitação, selecione corpo e, depois,, Editar.

   

2. Na área Parâmetro, agora você vê os três parâmetros esperados pela API: ID, Language e Text. Selecione ID e, depois, Editar.

   

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

   

   Parâmetro	Valor
   Descrição	Um identificador numérico para cada documento que você enviar

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

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

Baixar o arquivo OpenAPI atualizado

Você pode criar um conector personalizado a partir de um arquivo OpenAPI ou do zero (no Power Automate e no Power Apps). Independentemente de como o conector for criado, você poderá baixar a definição OpenAPI que o serviço usa internamente.

• Em Aplicativos Lógicos, baixe do conector personalizado.

  

• No Power Automate ou Power Apps, baixe a lista de conectores personalizados.

  

Teste o conector

Após criar 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, selecione Nova conexão.

   

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

   

3. Retorne para a página Teste e siga um destes procedimentos:

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

     

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

   

5. O conector chamará a API e você poderá analisar a resposta, que inclui a pontuação de sentimento.

   

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 ou obter o conector certificado 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.