Registar e utilizar conectores personalizados no PowerAppsRegister and use custom connectors in PowerApps

O PowerApps permite criar aplicações com todas as funcionalidades sem qualquer código de aplicação tradicional.PowerApps enables you to build full-featured apps with no traditional application code. Porém, em alguns casos, é preciso expandir as capacidades do PowerApps e os serviços Web são uma solução natural para tal.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. A sua aplicação pode ligar a um serviço, executar operações e devolver dados.Your app can connect to a service, perform operations, and get data back. Quando tiver um serviço Web que queira ligar ao PowerApps, registe o serviço como um conector personalizado.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. Este processo permite que o PowerApps compreenda as características da API Web, incluindo a autenticação que requer, as operações que suporta e os parâmetros e saídas para cada uma dessas operações.This process enables PowerApps to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

Neste tópico, vamos abordar os passos necessários para registar e utilizar um conector personalizado e iremos utilizar a API de Análise de Texto dos Serviços Cognitivos do Azure como exemplo.In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API as an example. Esta API identifica o idioma, sentimento e expressões-chave no texto que passa pela mesma.This API identifies the language, sentiment, and key phrases in text that you pass to it. A imagem seguinte mostra a interação entre o serviço, o conector personalizado que criamos a partir do mesmo e a aplicação que chama a API.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API, conector personalizado e aplicação

Pré-requisitosPrerequisites

  • Uma conta do PowerApps.A PowerApps account.
  • Um ficheiro OpenAPI no formato JSON, um URL para uma definição de OpenAPI ou uma Coleção do Postman para a API.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Se não tiver nenhum destes, iremos oferecer-lhe orientação.If you don't have any of these, we'll provide guidance for you.
  • Uma imagem para utilizar como um ícone para o conector personalizado (opcional).An image to use as an icon for your custom connector (optional).

Passos no processo de conector personalizadoSteps in the custom connector process

O processo de conector personalizado tem vários passos, que descrevemos resumidamente em baixo.The custom connector process has several steps, which we describe briefly below. Este artigo pressupõe que já tem uma API RESTful com algum tipo de acesso autenticado, pelo que iremos focar-se nos passos 3 a 6 no resto do artigo.This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. Para obter um exemplo dos passos 1 e 2, veja Criar uma API Web personalizada para o PowerApps.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Crie uma API RESTful no idioma e plataforma da sua preferência.Build a RESTful API in the language and platform of your choice. Para tecnologias Microsoft, recomendamos uma das seguintes.For Microsoft technologies, we recommend one of the following.

    • Funções do AzureAzure Functions
    • Aplicações Web do AzureAzure Web Apps
    • Aplicações API do AzureAzure API Apps
  2. Proteja a sua API com um dos seguintes mecanismos de autenticação.Secure your API using one of the following authentication mechanisms. Pode permitir o acesso não autenticado às suas APIs, mas não o recomendamos.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. Descreva a API de uma de duas formas padrão da indústria, para que o PowerApps possa ligar à mesma.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Um ficheiro OpenAPI (também conhecido como ficheiro Swagger)An OpenAPI file (also known as a Swagger file)
    • Uma Coleção do PostmanA Postman Collection

      Também pode criar um ficheiro OpenAPI no passo 4 como parte do processo de registo.You can also build an OpenAPI file in step 4 as part of the registration process.

  4. Registe o conector personalizado com um assistente no PowerApps, onde pode especificar uma descrição da API, detalhes de segurança e outras informações.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Utilize o conector personalizado numa aplicação.Use your custom connector in an app. Crie uma ligação para a API na sua aplicação e chame quaisquer operações que a forneça, tal como chama as funções nativas no PowerApps.Create a connection to the API in your app, and call any operations that the API provides, just like you call native functions in PowerApps.
  6. Partilhe o seu conector personalizado tal como faz outras ligações de dados no PowerApps.Share your custom connector like you do other data connections in PowerApps. Este passo é opcional, mas, muitas vezes, faz sentido partilhar conectores personalizados em vários criadores de aplicações.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

Descrever a sua APIDescribe your API

Partindo do princípio de que tem uma API com algum tipo de acesso autenticado, precisa de uma forma de descrever a API para que o PowerApps possa ligar a ela.Assuming you have an API with some type of authenticated access, you need a way to describe the API so that PowerApps can connect to it. Para tal, crie um ficheiro OpenAPI ou uma Coleção do Postman – o que pode fazer a partir de qualquer ponto final da API REST, incluindo:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • APIs disponíveis ao público.Publicly available APIs. Alguns exemplos incluem o Spotify, Uber, Slack, Rackspace e muitas mais.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • Uma API que cria e implementa em qualquer fornecedor de alojamento na cloud, incluindo o Azure, Amazon Web Services (AWS), Heroku, Google Cloud e muito mais.An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • Uma API de linha de negócio personalizada implementada na sua rede, desde que a API esteja exposta na Internet pública.A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

Os ficheiros OpenAPI e as Coleções do Postman utilizam formatos diferentes, mas ambos são documentos legíveis por máquina e de linguagem desconhecida que descrevem as operações e os parâmetros da API:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • Pode gerar estes documentos com várias ferramentas, consoante a linguagem e a plataforma na qual a API é criada.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. Veja a documentação da API de Análise de Texto para obter um exemplo de um ficheiro OpenAPI.See the Text Analytics API documentation for an example of an OpenAPI file.
  • Se ainda não tiver um ficheiro OpenAPI para a sua API e não quiser criar um, pode continuar a criar facilmente um conector personalizado através de uma Coleção do Postman.If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. Veja Criar uma Coleção do Postman para obter mais informações.See Create a Postman Collection for more information.
  • Por fim, o PowerApps utiliza o OpenAPI nos bastidores, pelo que uma Coleção do Postman é analisada e convertida num ficheiro de definição de OpenAPI.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Nota: O tamanho do ficheiro tem de ser inferior a 1 MB.Note: Your file size must be less than 1MB.

Introdução ao OpenAPI e ao PostmanGetting started with OpenAPI and Postman

Registar o conector personalizadoRegister your custom connector

Agora, vai utilizar o ficheiro OpenAPI ou a Coleção do Postman para registar o conector personalizado no PowerApps.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. Em powerapps.com, no menu à esquerda, selecione Ligações.In powerapps.com, in the left menu, select Connections. Selecione as reticências (...) e, em seguida, selecione Gerir conectores personalizados no canto superior direito.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Sugestão: se não souber onde pode gerir conectores personalizados num browser para dispositivos móveis, poderá ser num menu no canto superior esquerdo.Tip: If you can't find where to manage custom connectors in a mobile browser, it might be under a menu in the upper left corner.

    Criar um conector personalizado

  2. Selecione Criar um conector personalizado.Select Create custom connector.

    Propriedades do conector personalizado

  3. No separador Geral, escolha como pretende criar o conector personalizado.In the General tab, choose how you want to create the custom connector.

    • Carregar um ficheiro OpenAPIUpload an OpenAPI file
    • Utilizar um URL de OpenAPIUse an OpenAPI URL
    • Carregar uma Coleção do Postman V1Upload Postman Collection V1

      Como criar um conector personalizado

      Carregue um ícone para o conector personalizado.Upload an icon for your custom connector. Os campos Descrição, Anfitrião e URL Base são, normalmente, preenchidos automaticamente com as informações do ficheiro OpenAPI.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Se não forem preenchidos automaticamente, pode adicionar informações a esses campos.If they are not auto-populated, you can add information to those fields. Selecione Continuar.Select Continue.

  4. No separador Segurança, introduza as propriedades de autenticação.In the Security tab, enter any authentication properties.

    Tipos de autenticação

    • O tipo de autenticação é preenchido automaticamente com base no que está definido no seu objeto securityDefinitions do OpenAPI.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Segue-se um exemplo de OAuth2.0.Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • Se o ficheiro OpenAPI não utilizar o objeto securityDefintions, não são necessários valores adicionais.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Quando utilizar uma Coleção do Postman, o tipo de autenticação só é preenchido automaticamente se utilizar tipos de autenticação suportados, tais como OAuth 2.0 ou Básico.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Para obter um exemplo de como configurar a autenticação do Azure Active Directory (AAD), veja Criar uma API Web personalizada para o PowerApps.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. No separador Definições, todas as operações definidas no seu ficheiro OpenAPI ou Coleção do Postman, juntamente com os valores de pedido e resposta, são preenchidas automaticamente.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Se todas as operações necessárias forem definidas, pode avançar para o passo 6 do processo de registo sem fazer alterações neste ecrã.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Separador Definição

    Se pretender editar ações existentes ou adicionar novas ações ao conector personalizado, continue a ler abaixo.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. Se pretender adicionar uma nova ação que ainda não estava no seu ficheiro OpenAPI ou Coleção do Postman, selecione Nova ação no painel esquerdo e preencha a secção Geral com o nome, a descrição e a visibilidade da operação.If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. Na secção Pedido, selecione Importar a partir da amostra no canto superior direito.In the Request section, select Import from sample on the top right. No formulário no lado direito, cole num pedido de exemplo.In the form on the right, paste in a sample request. Os pedidos de exemplo estão, normalmente, disponíveis na documentação da API, onde pode obter informações para preencher os campos Verbo, URL do Pedido, Cabeçalhos e Corpo.Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. Veja a documentação da API de Análise de Texto para obter um exemplo.See the Text Analytics API documentation for an example.

      Importar a partir da amostra

    3. Selecione Importar para concluir a definição do pedido.Select Import to complete the request definition. Defina a resposta de forma semelhante.Define the response in a similar way.
  6. Assim que tiver todas as operações definidas, selecione Criar para criar o conector personalizado.Once you have all your operations defined, select Create to create your custom connector.
  7. Assim que tiver criado o seu conector personalizado, aceda ao separador Testar para testar as operações definidas na API.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Escolha uma ligação e forneça os parâmetros de entrada para testar uma operação.Choose a connection, and provide input parameters to test an operation.

    Testar o conector personalizado

    Se a chamada for realizada com êxito, receberá uma resposta válida.If the call is successful, you get a valid response.

    Testar a Resposta da API

Utilizar o conector personalizadoUse your custom connector

Agora que já registou a sua API, adicione o conector personalizado à sua aplicação, tal como faria com qualquer outra origem de dados.Now that you've registered your API, add the custom connector to your app like you would any other data source. Vamos analisar um breve exemplo aqui.We'll go through a brief example here. Para obter mais informações sobre ligações de dados, veja Adicionar uma ligação de dados no PowerApps.For more information about data connections, see Add a data connection in PowerApps.

  1. No PowerApps Studio, no painel da direita, clique ou toque em Adicionar origem de dados.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Clique ou toque no conector personalizado que criou.Click or tap the custom connector that you created.

  3. Conclua os passos necessários para iniciar sessão no serviço ao qual está a ligar.Complete any steps necessary to sign in to the service you're connecting to. Se a sua API utilizar a autenticação OAuth, poderá ser apresentado um ecrã de início de sessão.If your API uses OAuth authentication, you might be presented a sign-in screen. Para a autenticação da chave de API, poderá ser-lhe pedido um valor de chave.For API key authentication, you might be prompted for a key value.
  4. Chame a API na sua aplicação.Call the API in your app. Para o nosso exemplo, criámos uma aplicação que envia texto para os Serviços Cognitivos e recebe de volta uma classificação de sentimento de 0 a 1, que a aplicação mostra como uma percentagem.For our example, we created an app that submits text to Cognitive Services and gets back a sentiment score of 0 to 1, which the app shows as a percentage.

    • Com este conector, se começar a escrever "Az" na barra de fórmulas, verá a API e as operações que disponibiliza.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • A chamada completa é semelhante a esta, onde introduzimos texto do controlo TextInput e recebemos uma classificação para apresentar na aplicação:The complete call looks like this, where we pass in text from the TextInput control and get back a score to display in the app:

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
      
    • Fazemos um pouco mais na aplicação para processar os dados devolvidos, mas não é demasiado complicado.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

A aplicação concluída é semelhante à imagem seguinte.The finished app looks like the following image. É uma aplicação simples, mas ganha funcionalidade poderosa por ser capaz de chamar os Serviços Cognitivos através de um conector personalizado.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Quota e limitaçãoQuota and throttling

  • Veja a página Preços do PowerApps para obter detalhes sobre as quotas de criação de conectores personalizados.See the PowerApps Pricing page for details about custom connector creation quotas. Os conectores personalizados que são partilhados consigo não são contabilizados nesta quota.Custom connectors that are shared with you don't count against this quota.
  • Para cada ligação criada num conector personalizado, os utilizadores podem executar até 500 pedidos por minuto.For each connection created on a custom connector, users can make up to 500 requests per minute.

Partilhar o conector personalizadoShare your custom connector

Agora que tem um conector personalizado, pode partilhá-lo com outros utilizadores na sua organização.Now that you have a custom connector, you can share it with other users in your organization. Tenha em atenção que quando partilha uma API, os outros utilizadores podem começar a depender da mesma e eliminar um conector personalizado elimina todas as ligações para a API.Keep in mind that when you share an API, others might start to depend on it, and deleting a custom connector deletes all the connections to the API. Se pretender fornecer um conector para os utilizadores fora da sua organização, veja Descrição geral da certificação de conectores personalizados no PowerApps.If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. Em powerapps.com, no menu à esquerda, selecione Ligações.In powerapps.com, in the left menu, select Connections. Selecione as reticências (...) e, em seguida, selecione Gerir conectores personalizados no canto superior direito.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Nova ligação

  2. Selecione o botão de reticências (...) para o conector e, em seguida, selecione Ver propriedades.Select the ellipsis (. . .) button for your connector, then select View properties.

    Ver propriedades do conector

  3. Selecione a sua API, selecione Partilhar e, em seguida, introduza os utilizadores ou grupos a quem pretende conceder acesso à sua API.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Partilhar um conector personalizado

  4. Selecione Guardar.Select Save.

Passos seguintesNext steps

Saiba como criar uma Coleção do PostmanLearn how to create a Postman Collection

Utilizar uma API Web ASP.NET.Use an ASP.NET Web API.

Registar uma API do Azure Resource Manager.Register an Azure Resource Manager API.