Criar um conector personalizado para uma API Web no PowerAppsBuild a custom connector for a Web API in PowerApps

Este tutorial mostra como começar a criar uma API Web ASP.NET, hospedá-la nos Aplicativos Web do Azure, habilitar a autenticação do Azure Active Directory e, em seguida, registrar a API Web ASP.NET no PowerApps.This tutorial shows you how to start bulding an ASP.NET Web API, host it on Azure Web Apps, enable Azure Active Directory authentication, and then register the ASP.NET Web API in PowerApps. Depois que a API é registrada, você pode conectá-la e chamá-la no aplicativo.After the API is registered, you can connect to it and call it from your app.

Pré-requisitosPrerequisites

Criar uma API Web ASP.NET e implantá-la no AzureCreate an ASP.NET Web API and deploy it to Azure

  1. No Visual Studio, clique em Arquivo > Novo Projeto para criar um novo aplicativo Web ASP.NET C#.In Visual Studio, click File > New Project to create a new C# ASP.NET web application.

    Novo aplicativo Web

  2. Selecione o modelo de API Web.Select the Web API template. Deixe Host na nuvem marcado.Leave Host in the cloud checked. Clique em Alterar autenticação.Click Change Authentication.

    Novo modelo de projeto Web

  3. Selecione Sem autenticação e, em seguida, clique em OK.Select No Authentication, and then click OK.

    Sem autenticação

  4. Clique em OK na caixa de diálogo Novo projeto ASP.NET.Click OK on the New ASP.NET Project dialog. A caixa de diálogo Configurar aplicativo Web do Microsoft Azure aparece.The Configure Microsoft Azure Web App dialog appears.

    Configurar aplicativo Web do Microsoft Azure]]

    Selecione sua conta do Azure, digite um nome do aplicativo Web (ou deixe o padrão) e selecione a Assinatura do Azure.Select your Azure account, type a Web App name (or leave the default), and select your Azure Subscription. Selecione ou crie um Plano do Serviço de Aplicativo (uma coleção de aplicativos Web dentro de sua assinatura).Select or create an App Service plan (a collection of Web Apps within your subscription). Selecione ou crie uma Grupo de recursos (um agrupamento de recursos do Azure em sua assinatura).Select or create a Resource group (a grouping of Azure resources within your subscription). Selecione a região na qual o aplicativo Web deve ser implantado.Select the region where the Web App should be deployed. Se for necessário para sua API Web, selecione ou crie um Servidor de banco de dados do Azure.If required for your Web API, select or create an Azure Database server. Por fim, clique em OK.Finally, click OK.

  5. Crie a API Web.Build out your Web API.

    Observação: se você ainda não tem um código pronto para uma API Web, tente o tutorial Introdução à API Web ASP.NET 2 (C#).Note: If you don't already have code ready for a Web API, try the tutorial Getting Started with ASP.NET Web API 2 (C#).

  6. Para conectar nossa API Web ao PowerApps, precisaremos de um arquivo OpenAPI que descreve suas operações.To connect our Web API to PowerApps, we'll need an OpenAPI file that describes its operations. Você poderá escrever um OpenAPI de sua autoria usando o editor online, mas, para este tutorial, você usará uma ferramenta de software livre chamada Swashbuckle.You could write an OpenAPI of your own using the online editor, but for this tutorial, you'll use an open-source tool named Swashbuckle. Instale o pacote Nuget do Swashbuckle no projeto do Visual Studio clicando em Ferramentas > Gerenciador de Pacotes NuGet > Console do Gerenciador de Pacotes e, em seguida, no Console do Gerenciador de Pacotes, digite o comando Install-Package Swashbuckle.Install the Swashbuckle Nuget package in your Visual Studio project by clicking Tools > NuGet Package Manager > Package Manager Console, and then, in the Package Manager Console, type the command Install-Package Swashbuckle.

    Pacote de instalação Swashbuckle

    Dica: quando você executar o aplicativo de API Web depois de instalar o Swashbuckle, um arquivo OpenAPI será gerado na URL http://<your root URL>/swagger/docs/v1.Tip: When you run your Web API application after installing Swashbuckle, an OpenAPI file will now be generated at the URL http://<your root URL>/swagger/docs/v1. Uma interface do usuário gerada também estará disponível em http://<your root URL>/swagger.A generated user interface is also available at http://<your root URL>/swagger.

  7. Quando sua API Web estiver pronta, publique-a no Azure.When your Web API is ready, publish it to Azure. Para publicar no Visual Studio, clique com o botão direito do mouse no projeto Web no Gerenciador de Soluções, clique em Publicar... e, em seguida, siga as instruções na caixa de diálogo Publicar.To publish from Visual Studio, right-click on the web project in Solution Explorer, click Publish..., and then follow the prompts in the Publish dialog.
  8. Recupere o JSON de OpenAPI acessando https://<azure-webapp-url>/swagger/docs/v1.Retrieve the OpenAPI JSON by navigating to https://<azure-webapp-url>/swagger/docs/v1. Salve o conteúdo como um arquivo JSON.Save the content as a JSON file. Dependendo do seu navegador, você precisará copiar e colar o texto em um arquivo de texto vazio.Depending on your browser, you may need to copy and paste the text into an empty text file.

    Importante: um documento OpenAPI com IDs de operação duplicadas é inválido.Important: An OpenAPI document with duplicate operation IDs is invalid. Se você estiver usando o modelo C# de exemplo, a ID da operação Values_Get será repetida duas vezes.If you are using the sample C# template, the operation ID Values_Get is repeated twice. Você pode corrigir isso alterando uma instância para Value_Get e publicando-a novamente.You can correct this by changing one instance to Value_Get and re-publishing. Também é possível baixar um arquivo OpenAPI de exemplo neste tutorial.You can also download a sample OpenAPI file from this tutorial. Certifique-se de remover os comentários (começando com //) antes de usá-lo.Be sure to remove the comments (starting with //) before using it.

Configurar autenticação do Azure Active DirectorySet up Azure Active Directory authentication

Agora, você criará dois aplicativos do AAD (Azure Active Directory) no Azure.You will now create two Azure Active Directory (AAD) applications in Azure. Para obter um exemplo de como fazer isso, consulte o tutorial do Azure Resource Manager.For an example of how to do this, see the Azure Resource Manager tutorial.

Importante Os dois aplicativos devem estar no mesmo diretório.Important Both apps must be in the same directory.

Primeiro aplicativo AAD: proteção da API WebFirst AAD application: Securing the Web API

O primeiro aplicativo AAD é usado para proteger a API Web.The first AAD application is used to secure the Web API. Chame-o de webAPI.Name it webAPI. Siga as etapas do tutorial com links acima (apenas a seção intitulada “Habilitar a autenticação no Azure Active Directory”) com os seguintes valores:Follow the above linked tutorial steps (just the section titled "Enable authentication in Azure Active Directory") with the following values:

  • URL de Entrada: https://login.windows.netSign-on URL: https://login.windows.net
  • URL de resposta: https://<your-root-url>/.auth/login/aad/callbackReply URL: https://<your-root-url>/.auth/login/aad/callback
  • Não é necessária uma chave de cliente.There is no need for a client key.
  • Não é necessário delegar permissões.There is no need to delegate any permissions.
  • Importante: anote a ID do aplicativo.Important: Note the application ID. Você precisará dela mais tarde.You will need it later.

Segundo aplicativo do AAD: protegendo o conector personalizado e o acesso delegadoSecond AAD application: Securing the custom connector and delegated access

O segundo aplicativo do AAD é usado para proteger o registro do conector personalizado e adquirir acesso delegado à API Web protegida pelo primeiro aplicativo.The second AAD application is used to secure the custom connector registration and acquire delegated access to the Web API protected by the first application. Nomeie esse como webAPI-customAPI.Name this one webAPI-customAPI .

  • URL de Entrada: https://login.windows.netSign-on URL: https://login.windows.net
  • URL de resposta: https://msmanaged-na.consent.azure-apim.net/redirectReply URL: https://msmanaged-na.consent.azure-apim.net/redirect
  • Adicione permissões para ter acesso delegado à API Web.Add permissions to have delegated access to Web API.
  • Você também precisará da ID do aplicativo desse aplicativo mais tarde, portanto, anote-a.You need the application ID of this application later as well, so note it.
  • Gere uma chave de cliente e armazene-a em algum lugar seguro.Generate a client key and store is somewhere safe. Precisaremos dessa chave mais tarde.We need this key later.

Adicionar autenticação ao seu aplicativo Web do AzureAdd authentication to your Azure Web App

  1. Conecte-se ao Portal do Azure e localize o aplicativo Web implantado na primeira seção.Sign in to the Azure portal and then find your Web App that you deployed in the first section.
  2. Clique em Configurações e, em seguida, selecione Autenticação / Autorização.Click Settings, and then select Authentication / Authorization.
  3. Ative Autenticação do Serviço de Aplicativo e, em seguida, selecione Azure Active Directory.Turn on App Service Authentication and then select Azure Active Directory. Na próxima folha, selecione Expresso.On the next blade, select Express.
  4. Clique em Selecionar aplicativo AD existente e selecione o aplicativo AAD webAPI criado anteriormente.Click Select Existing AD App, and select the webAPI AAD application you created earlier.

Agora, você poderá usar o AAD para autenticar seu aplicativo Web.You should now be able to use AAD to authenticate your web application.

Adicionar o conector personalizado ao PowerAppsAdd the custom connector to PowerApps

  1. Modifique o arquivo OpenAPI para adicionar o objeto securityDefintions e a autenticação do AAD usada para o Aplicativo Web.Modify your OpenAPI file to add the securityDefintions object and AAD authentication used for the Web App. A seção do arquivo OpenAPI com a propriedade host deve ter esta aparência:The section of your OpenAPI file with the host property should look like this:
// File header should be above here...

"host": "<your-root-url>",
"schemes": [
    "https"         //Make sure this is https!
],
"securityDefinitions": {
    "AAD": {
        "type": "oauth2",
        "flow": "implicit",
        "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
        "scopes": {}
    }
},

// The rest of the OpenAPI document follows...
  1. Navegue até PowerApps e adicione um conector personalizado, conforme descrito em Registrar e usar conectores personalizados no PowerApps.Browse to PowerApps, and add a custom connector as described in Register and use custom connectors in PowerApps.
  2. Depois de carregar o arquivo OpenAPI, o assistente detecta automaticamente que você está usando a autenticação do AAD para a API Web.Once you have uploaded your OpenAPI file, the wizard auto-detects that you are using AAD authentication for your Web API.
  3. Configure a autenticação do AAD para o conector personalizado.Configure the AAD authentication for the custom connector.

    • ID do cliente: ID do cliente de webAPI-CustomAPIClient ID: Client ID of webAPI-CustomAPI
    • Segredo: Chave do cliente de webAPI-CustomAPISecret: Client key of webAPI-CustomAPI
    • URL de logon: https://login.windows.netLogin URL: https://login.windows.net
    • ResourceUri: ID do cliente de webAPIResourceUri: Client ID of webAPI
  4. Clique em Criar e crie uma conexão com o conector personalizado.Click Create and creating a connection to the custom connector.

Próximas etapasNext Steps

Acompanhe o tutorial de conectores personalizados do Azure Resource Manager.Walk through the Azure Resource Manager custom connector tutorial.