Criar um conector personalizado de uma definição OpenAPI

  • Artigo

Observação

Esse tópico faz parte de uma série de tutoriais sobre a criação e o uso de conectores personalizados nos Aplicativos Lógicos do Azure, no Microsoft Power Automate e no Microsoft Power Apps. Certifique-se de ler a visão geral do conector personalizado para entender o processo.

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:

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

Observação

Uma definição OpenAPI precisa estar em OpenAPI 2.0 (anteriormente conhecido como Swagger). Definições de OpenAPI que estão no formato OpenAPI 3.0 não são compatíveis.

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.

    Edite o Conector de Aplicativos Lógicos.

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

    Carregue o arquivo OpenAPI.

Observação

Este tutorial se concentra em um API REST, mas você também pode usar uma API SOAP com Aplicativos Lógicos.

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.

    Selecione o conector personalizado.

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

    Importe um arquivo OpenAPI.

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

    Carregue uma coleção.

    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.

    Página Geral do conector personalizado.

    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.

Parâmetros da chave de 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.

    Página Definição - ações e gatilhos.

  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

      Página Definição - geral.

  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.

    Página Definição – solicitação.

    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.

    Página Definição – resposta.

    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.

    Página Definição - validação.

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.

    Editar o corpo da solicitação.

  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.

    Editar a id do corpo da solicitação.

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

    Editar a propriedade do esquema.

    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.

    Baixe a definição de OpenAPI para Aplicativos Lógicos.

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

    Baixe a definição de OpenAPI para o Power Automate.

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.

Importante

Ao usar uma chave de API, recomendamos não testar o conector logo após a criação. Pode levar alguns minutos até que o conector esteja pronto para se conectar à API.

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

    Nova conexão.

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

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

      Atualizar conexão.

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

      Ícone de engrenagem no serviço.

  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.

    Testar operação.

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

    Resposta do conector.

Próximas etapas

Agora que você criou um conector personalizado e definiu os comportamentos, poderá usar o conector.

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.

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.