O PowerApps permite que você crie aplicativos em destaque completos sem nenhum código de aplicativo tradicional. Mas em alguns casos, você precisa estender as funcionalidades do PowerApps e os serviços Web são um ajuste perfeito para isso. Seu aplicativo pode se conectar a um serviço, executar operações e obter dados de volta. Quando você tiver um serviço Web ao qual você deseja se conectar com o PowerApps, registre o serviço como um conector personalizado. Esse processo permite que o PowerApps entenda as características da API Web, incluindo a autenticação necessária, as operações às quais ele dá suporte e os parâmetros e as saídas para cada uma dessas operações.

Neste tópico, veremos as etapas necessárias para registrar e usar um conector personalizado e usaremos a API de Análise de Texto dos Serviços Cognitivos do Azure como exemplo. Essa API identifica o idioma, o sentimento e as frases-chave no texto que você passa para ela. A imagem a seguir mostra a interação entre o serviço, o conector personalizado que criamos com base nele e o aplicativo que chama a API.

API, conector personalizado e aplicativo

Pré-requisitos

  • Uma conta do PowerApps.
  • Um arquivo OpenAPI no formato JSON, uma URL para uma definição de OpenAPI ou uma Coleção Postman para a API. Caso não tenha nenhum desses, forneceremos diretrizes a você.
  • Uma imagem a ser usada como um ícone do conector personalizado (opcional).

Etapas do processo do conector personalizado

O processo do conector personalizado apresenta várias etapas, que descrevemos brevemente abaixo. Este artigo pressupõe que você já tenha uma API RESTful com algum tipo de acesso autenticado e, portanto, nos concentraremos nas etapas 3 a 6 no restante do artigo. Para obter um exemplo das etapas 1 e 2, consulte Criar uma API Web personalizada para o PowerApps.

  1. Criar uma API RESTful na linguagem e plataforma de sua escolha. Para tecnologias da Microsoft, recomendamos uma das plataformas a seguir.

    • Funções do Azure
    • Aplicativos Web do Azure
    • Aplicativos de API do Azure
  2. Proteger sua API usando um dos mecanismos de autenticação a seguir. Você pode permitir o acesso não autenticado às APIs, mas isso não é recomendável.

  3. Descrever a API usando uma das duas maneiras padrão da indústria, de forma que o PowerApps possa se conectar a ela.

    • Um arquivo OpenAPI (também conhecido como um arquivo Swagger)
    • Uma Coleção Postman

    Você também pode criar um arquivo OpenAPI na etapa 4 como parte do processo de registro.

  4. Registrar o conector personalizado usando um assistente do PowerApps, no qual você especifica uma descrição da API, os detalhes de segurança e outras informações.

  5. Usar o conector personalizado em um aplicativo. Crie uma conexão com a API no aplicativo e chame todas as operações fornecidas pela API, assim como você chama funções nativas no PowerApps.

  6. Compartilhar o conector personalizado assim como você faz outras conexões de dados no PowerApps. Esta etapa é opcional, mas geralmente faz sentido compartilhar conectores personalizados entre vários criadores de aplicativos.

Descrever a API

Supondo que você tenha uma API com algum tipo de acesso autenticado, você precisa de uma maneira de descrever a API de forma que o PowerApps possa se conectar a ela. Para fazer isso, você cria um arquivo OpenAPI ou uma Coleção Postman – o que pode ser feito em qualquer ponto de extremidade de API REST, incluindo:

  • APIs disponíveis publicamente. Alguns exemplos incluem Spotify, Uber, Slack, Rackspace e muito mais.
  • Uma API criada e implantada em qualquer provedor de hospedagem na nuvem, incluindo Azure, AWS (Amazon Web Services), Heroku, Google Cloud e muito mais.
  • Uma API de linha de negócios personalizada implantada na sua rede, desde que a API seja exposta na Internet pública.

Os arquivos OpenAPI e as Coleções Postman usam formatos diferentes, mas ambos são documentos legíveis por computador independente de linguagem que descrevem as operações e os parâmetros da API:

  • É possível gerar esses documentos usando uma variedade de ferramentas, dependendo da linguagem e da plataforma com base nas quais a API foi criada. Consulte a documentação da API de Análise de Texto para obter um exemplo de um arquivo OpenAPI.
  • Se você ainda não tiver um arquivo OpenAPI para a API e não desejar criar um, ainda assim poderá facilmente criar um conector personalizado usando uma Coleção Postman. Consulte Criar uma Coleção Postman para obter mais informações.
  • Em última análise, o PowerApps usa o OpenAPI nos bastidores e, portanto, uma Coleção Postman é analisada e convertida em um arquivo de definição de OpenAPI.

Observação: o tamanho do arquivo deve ser menor que 1 MB.

Introdução ao OpenAPI e ao Postman

Registrar o conector personalizado

Agora, você usará o arquivo OpenAPI ou a Coleção Postman para registrar o conector personalizado no PowerApps.

  1. Em powerapps.com, no menu à esquerda, selecione Conexões. Selecione as reticências (...) e, em seguida, selecione Gerenciar conectores personalizados no canto superior direito.

    Dica: se você não souber o local em que os conectores personalizados são gerenciados em um navegador móvel, ele poderá estar em um menu no canto superior esquerdo.

    Criar um conector personalizado

  2. Selecione Criar um conector personalizado.

    Propriedades do conector personalizado

  3. Na guia Geral, escolha como você deseja criar o conector personalizado.

    • Carregar um arquivo OpenAPI
    • Usar uma URL OpenAPI
    • Carregar a Coleção Postman V1

    Como criar um conector personalizado

    Carregue um ícone para o conector personalizado. Os campos Descrição, Host e URL Base são normalmente populados automaticamente com as informações do arquivo OpenAPI. Se eles não forem populados automaticamente, você poderá adicionar informações a esses campos. Selecione Continuar.

  4. Na guia Segurança, insira as propriedades de autenticação.

    Tipos de autenticação

    • O tipo de autenticação é populado automaticamente com base no que está definido no objeto OpenAPI securityDefinitions. Veja abaixo um exemplo do OAuth2.0.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • Se o arquivo OpenAPI não usar o objeto securityDefintions, não serão necessários valores adicionais.

    • Ao usar uma Coleção Postman, o tipo de autenticação será populado automaticamente somente quando tipos de autenticação com suporte forem usados, como OAuth 2.0 ou Básico.

    • Para obter um exemplo de como configurar a autenticação do AAD (Azure Active Directory), consulte Criar uma API Web personalizada para o PowerApps.

  5. Na guia Definições, todas as operações definidas no arquivo OpenAPI ou na Coleção Postman, juntamente com os valores de solicitação e resposta, são populadas automaticamente. Caso todas as operações necessárias estejam definidas, vá para a etapa 6 do processo de registro sem fazer alterações nessa tela.

    Guia Definição

    Se você desejar editar as ações existentes ou adicionar novas ações ao conector personalizado, continue lendo abaixo.

    1. Caso você deseje adicionar uma nova ação que ainda não estava no arquivo OpenAPI nem na Coleção Postman, selecione Nova ação no painel esquerdo e preencha a seção Geral com o nome, a descrição e a visibilidade da operação.
    2. Na seção Solicitação, selecione Importar da amostra no canto superior direito. No formulário à direita, cole uma solicitação de exemplo. Em geral, as solicitações de amostra estão disponíveis na documentação da API, na qual você pode obter informações para preencher os campos Verbo, URL de Solicitação, Cabeçalhos e Corpo. Consulte a documentação da API de Análise de Texto para obter um exemplo.

      Importar da amostra

    3. Selecione Importar para concluir a definição de solicitação. Defina a resposta de uma maneira semelhante.

  6. Depois de definir todas as operações, selecione Criar para criar o conector personalizado.

  7. Depois de criar o conector personalizado, acesse a guia Teste para testar as operações definidas na API. Escolha uma conexão e forneça parâmetros de entrada para testar uma operação.

    Testar conector personalizado

    Se a chamada for bem-sucedida, você obterá uma resposta válida.

    Testar resposta da API

Usar o conector personalizado

Agora que você já registrou sua API, adicione o conector personalizado ao aplicativo, assim como faria com qualquer outra fonte de dados. Vamos examinar um exemplo breve aqui. Para obter mais informações sobre conexões de dados, consulte Adicionar uma conexão de dados no PowerApps.

  1. No PowerApps Studio, no painel direito, clique ou toque em Adicionar fonte de dados.

  2. Clique ou toque no conector personalizado que você criou.

  3. Conclua as etapas necessárias para entrar no serviço ao qual você está se conectando. Se a API usar a autenticação OAuth, talvez seja exibida uma tela de conexão. Para a autenticação de chave de API, talvez você precise inserir um valor de chave.

  4. Chame a API no aplicativo. Para nosso exemplo, criamos um aplicativo que envia o texto para os Serviços Cognitivos e recebe uma pontuação de sentimento de 0 a 1, que o aplicativo mostra como um percentual.

    • Com esse conector, se você começar a digitar “Az” na barra de fórmulas, verá a API e as operações que ela disponibiliza.

    • A chamada completa é parecida com esta, na qual passamos o texto do controle TextInput e obtemos uma pontuação a ser exibida no aplicativo:

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
      
    • Fazemos um pouco mais de trabalho no aplicativo para manipular os dados que voltam, mas isso não é muito complicado.

O aplicativo concluído é parecido com a imagem a seguir. É um aplicativo simples, mas obtém uma funcionalidade avançada com a capacidade de chamar os Serviços Cognitivos por meio de um conector personalizado.

Cotas e limitação

  • Consulte a página Preços do PowerApps para obter detalhes sobre as cotas de criação de conectores personalizados. Os conectores personalizados compartilhados com você não são considerados nessa cota.
  • Para cada conexão criada em um conector personalizado, os usuários podem criar até 500 solicitações por minuto.

Compartilhar o conector personalizado

Agora que você tem um conector personalizado, você pode compartilhá-lo com outros usuários de sua organização. Tenha em mente que quando você compartilha uma API, outras pessoas podem começar a depender dela e a exclusão de um conector personalizado exclui todas as conexões com a API. Se você desejar fornecer um conector para os usuários fora de sua organização, consulte Visão geral da certificação de conectores personalizados no PowerApps.

  1. Em powerapps.com, no menu à esquerda, selecione Conexões. Selecione as reticências (...) e, em seguida, selecione Gerenciar conectores personalizados no canto superior direito.

    Nova conexão

  2. Selecione o botão de reticências (...) do conector e, em seguida, selecione Exibir propriedades.

    Exibir as propriedades do conector

  3. Selecione sua API, selecione Compartilhar e, em seguida, insira os usuários ou grupos aos quais você deseja permitir acesso à sua API.

    Compartilhar um conector personalizado

  4. Selecione Salvar.

Próximas etapas

Saiba como criar uma Coleção Postman

Usar uma API Web ASP.NET.

Registrar uma API do Azure Resource Manager.