Criar um conector personalizado para uma API web

Este tutorial mostra-lhe como começar a criar uma API Web ASP.NET, hospedá-la na caraterística de Aplicações Web do Azure do Serviço de Aplicações do Azure, ativar a autenticação Microsoft Entra ID e, em seguida, registar a API Web ASP.NET no Power Automate. Depois de a API estar registada, pode ligar-se à mesma e chamá-la a partir do seu fluxo. Também pode registar e chamar a API a partir do Power Apps ou do Azure Logic Apps.

Pré-requisitos

• Visual Studio 2013 ou superior. Este tutorial utiliza o Visual Studio 2015.

• Código para a sua API Web. Se não tiver, experimente este tutorial: introdução ao Web API 2 (C#) ASP.NET.

• Uma subscrição do Azure. Se não tiver uma subscrição, poderá iniciar uma conta Azure gratuita. Em alternativa, pode inscrever-se para obter uma subscrição pay as you go.

Criar e implementar uma aplicação Web ASP.NET no Azure

Para este tutorial, crie uma aplicação Web ASP.NET Visual C#.

1. Abra o Visual Studio e, em seguida, selecione Ficheiro > Novo projeto.

   1. Expanda Instalado, aceda a Modelos > Visual C# > Web e, em seguida, selecione Aplicação Web ASP.NET.

   2. Introduza um nome de projeto, localização e nome da solução para a sua aplicação e, em seguida, selecione OK.

   

2. Na caixa Nova Aplicação Web ASP.NET, selecione o modelo API Web,certifique-se de que a caixa de verificação Hospedar na cloud está selecionada e, em seguida, selecione Alterar Autenticação.

   

3. Selecione Sem Autenticação e, em seguida, selecione OK. Pode configurar a autenticação mais tarde.

   

4. Quando a caixa Nova aplicação Web ASP.NET voltar a aparecer, selecione OK.

5. Na caixa Criar serviço de aplicação, reveja as definições de hospedagem descritas na tabela que se segue, efetue as alterações pretendidas e, em seguida, selecione Criar.

   Um plano do serviço de aplicações representa uma coleção de recursos físicos utilizados para alojar aplicações na sua subscrição do Azure. Obter informações sobre o Serviço de Aplicações.

   

   Definição	Valor sugerido	Descrição
   A sua conta escolar ou profissional do Azure ou a sua conta Microsoft pessoal	sua-conta-utilizador	Selecione a sua conta de utilizador.
   Nome da aplicação web	custom-Web-API-app-name ou o nome predefinido	Introduza o nome para a sua aplicação de API Web, que é utilizada no URL da sua aplicação; por exemplo: http://web-api-app-name.
   Subscrição	Azure-subscrição-nome	Selecione a subscrição do Azure que pretende utilizar.
   Grupo de Recursos	Azure-recurso-grupo-nome	Selecione um grupo de recursos do Azure existente ou, caso ainda não o tenha feito, crie um grupo de recursos. Nota: os grupos de recursos do Azure organizam os recursos do Azure na sua subscrição do Azure.
   Plano do Serviço de Aplicações	Aplicação-serviço-plano-nome	Selecione um plano do serviço de aplicação existente ou, se ainda não o tiver feito, crie um plano.

   Se criar um plano do serviço de aplicações, especifique o que se segue.

   Definição	Valor sugerido	Descrição
   Location	implementação-região	Selecione a região para implementação da sua aplicação.
   Tamanho	Aplicação-serviço-plano-tamanho	Selecione o tamanho do plano, o que determina o custo e a capacidade computacional do seu plano de serviço.

   Para configurar outros recursos necessários para a sua aplicação, selecione Explorar serviços adicionais do Azure.

   Definição	Valor sugerido	Descrição
   Tipo de Recurso	Azure-recurso-tipo	Selecione e configure quaisquer recursos adicionais necessários para a sua aplicação.

6. Depois do Visual Studio implementar o projeto, crie o código para a sua aplicação.

Criar um ficheiro OpenAPI (swagger) que descreva a sua API Web

Para ligar a sua aplicação API Web ao Power Automate, ao Power Apps ou a Logic Apps, precisa de um ficheiro OpenAPI (anteriormente Swagger) que descreva as operações da API. Pode escrever a sua própria definição OpenAPI para a API com o editor online do Swagger, mas este tutorial utiliza uma ferramenta open source denominada Swashbuckle.

1. Se ainda não tiver instalado, instale o pacote Swashbuckle NuGet no seu projeto Visual Studio:

   1. No Visual Studio, selecione Ferramentas > Gestor de pacote NuGet > Consola do Gestor de Pacotes.

   2. Na consola do gestor de pacotes, aceda ao diretório do projeto da sua aplicação, caso ainda não esteja lá ( execute Set-Location "project-path") e execute este cmdlet do PowerShell:

      Install-Package Swashbuckle

      

   Dica

   Se executar a aplicação depois de instalar o Swashbuckle, o Swashbuckle gera um ficheiro OpenAPI neste URL:

     http://{your-web-api-app-root-URL}/swagger/docs/v1

   O Swashbuckle também gera uma interface de utilizador neste URL:
   

     http://{your-web-api-app-root-URL}/swagger

2. Quando estiver pronto, publique a sua aplicação API Web no Azure. Para publicar a partir do Visual Studio, clique com o botão direito do rato no seu projeto Web no Explorador de Soluções, selecione Publicar e siga os avisos.

   Importante

   Se um documento OpenAPI contiver IDs de operação duplicados, serão inválidos. O modelo de C# de amostra repete o ID da operação, Values_Get.

   Se tiver utilizado o modelo de C# de amostra, pode corrigir este problema alterando uma instância de ID da operação para Value_Get e voltando a publicar.

3. Obtenha o documento OpenAPI navegando para esta localização:

   http://{your-web-api-app-root-URL}/swagger/docs/v1

   Também pode transferir um documento OpenAPI de amostra deste tutorial. Certifique-se de que remove os comentários, que começam com //, antes de utilizar o documento.

4. Guarde o conteúdo como um ficheiro JSON. Consoante o seu browser, pode ter de copiar e colar o texto num ficheiro de texto vazio.

Configurar a autenticação do Microsoft Entra ID

Agora, irá criar duas aplicações Microsoft Entra ID no Azure. Para mais informações, aceda a Integrar aplicações com o Microsoft Entra ID.

Importante

Ambas as aplicações têm de estar no mesmo diretório.

Primeira aplicação Microsoft Entra ID: proteger a API Web

A primeira aplicação Microsoft Entra ID é utilizada para proteger a API Web. Dê-lhe o nome webAPI. Pode ativar a autenticação do Microsoft Entra ID na sua API Web seguindo estes passos com os seguintes valores:

• URL de início de sessão: https://login.windows.net
• URL da resposta: https://<your-root-url>/.auth/login/aad/callback
• Não precisa de uma chave de cliente.
• Não precisa de delegar quaisquer permissões.
• Copie a ID da aplicação, porque necessita dela mais tarde.

Segunda aplicação Microsoft Entra ID: proteger o conector personalizado e o acesso delegado

A segunda aplicação Microsoft Entra ID é utilizada para proteger o registo do conetor personalizado e adquirir acesso delegado à API Web protegida pela primeira aplicação. Dê-lhe o nome webAPI-customAPI.

• URL de início de sessão: https://login.windows.net
• URL da resposta: https://msmanaged-na.consent.azure-apim.net/redirect
• Adicione permissões para ter acesso delegado à Web API.
• Copie a ID da aplicação, porque necessita dela mais tarde.
• Gerar uma chave de cliente e copie-a, porque necessita dela mais tarde.

Adicionar autenticação à sua aplicação Web do Azure

1. Inicie sessão no Portal do Azure e, em seguida, localize a aplicação Web que implementou na primeira secção.

2. Selecione Definições e, em seguida, selecione Autenticação/Autorização.

3. Ative a autenticação do serviço de aplicação e, em seguida, selecione Azure Active Directory. No painel seguinte, selecione Expresso.

4. Selecione Selecionar Aplicação AD Existente e, em seguida, selecione a aplicação webAPI do Microsoft Entra ID que criou anteriormente.

Agora, deverá conseguir utilizar o Microsoft Entra ID para autenticar a sua aplicação Web.

Adicionar o conector personalizado ao Power Automate

1. Modifique o OpenAPI para adicionar o objeto securityDefintions e a autenticação do Microsoft Entra ID utilizados para a aplicação Web. A secção do OpenAPI com a propriedade host deve ter o seguinte aspeto:

// File header should be above here...

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

// The rest of the OpenAPI follows...

2. Navegue até Power Automate e adicione um conector personalizado, conforme descrito em Utilizar conectores personalizados no Power Automate.

3. Depois de carregar o OpenAPI, o assistente deteta automaticamente que está a utilizar a autenticação do Microsoft Entra ID para a API Web.

4. Configure a autenticação do Microsoft Entra ID para o conector personalizado.

• ID de cliente: ID de cliente de webAPI-CustomAPI
• Segredo: chave de cliente de webAPI-CustomAPI
• URL de início de sessão: https://login.windows.net
• ResourceUri: ID de cliente de webAPI

5. Selecione Criar para criar uma ligação ao conector personalizado.

Informações relacionadas

Obter mais informações sobre a autenticação do Microsoft Entra ID

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.