Criar um conector personalizado para uma API Web

Este tutorial mostra como começar a criar um ASP.NET Web API, hospedá-lo no recurso Azure Web Apps de Azure App Service, habilitar Microsoft Entra ID autenticação e registrar o ASP.NET Web API em Power Automate. Depois de a API ser registrada, você pode conectá-la e chamá-la a partir de seu fluxo. Você também pode ter a opção de:

Pré-requisitos

Criar e implantar um aplicativo Web ASP.NET para Azure

Para este tutorial, crie um aplicativo Web ASP.NET Visual C#.

  1. Abra Visual Studio e selecione File>New Project.

    1. Expanda Instalado, acesse Templates>Visual C#>Web e selecione ASP.NET Aplicativo Web.

    2. Informe um nome de projeto, local e nome da solução para seu aplicativo e escolha OK.

    Screenshot mostrando um novo aplicativo Web ASP.NET Visual C#.

  2. Na caixa New ASP.NET Web Application box, selecione o modelo Web API, verifique se a caixa de seleção Host na nuvem está selecionada e, em seguida, selecione Change Authentication.

    Imagem da caixa de diálogo Novo aplicativo Web ASP.NET.

  3. Selecione Sem Autenticação e selecione OK. Você pode configurar a autenticação posteriormente.

    Selecione Sem Autenticação.

  4. Quando a caixa New ASP.NET Web Application reaparecer, selecione OK.

  5. Na caixa Criar Serviço de Aplicativo, revise as configurações de hospedagem descritas na tabela a seguir, faça as alterações desejadas e escolha Criar.

    Um plano App Service representa uma coleção de recursos físicos usados para hospedar aplicativos em sua assinatura Azure. Saiba mais sobre o Serviço de Aplicativo.

    Criar Serviço de Aplicativo.

    Configuração Valor sugerido Descrição
    Sua conta corporativa ou de estudante Azure ou sua conta pessoal da Microsoft your-user-account Selecione sua conta de usuário.
    Nome do aplicativo Web custom-web-api-app-name ou o nome padrão Digite o nome do seu aplicativo de API Web, usado na URL do seu aplicativo, por exemplo: http://web-api-app-name.
    Subscription Azure-subscription-name Selecione a assinatura Azure que você deseja usar.
    Grupo de Recursos Azure-resource-group-name Selecione um grupo de recursos Azure existente ou, se ainda não tiver criado, crie um grupo de recursos.

    Nota: um grupo de recursos do Azure organiza recursos do Azure em sua assinatura do Azure.
    Plano do Serviço de Aplicativo App-Service-plan-name Selecione um plano existente do Serviço de Aplicativo ou, se ainda não fez isso, crie um plano.

    Se você criar um plano do Serviço de Aplicativo, especifique o seguinte.

    Configuração Valor sugerido Descrição
    Localidade deployment-region Selecione a região para implantar seu aplicativo.
    Tamanho tamanho-do-plano-de-serviço-de-aplicativo Selecione o tamanho do seu plano, que determina o custo e a capacidade de recursos de computação do seu plano de serviço.

    Para configurar outros recursos exigidos pelo aplicativo, selecione Explore serviços de Azure adicionais.

    Configuração Valor sugerido Descrição
    Tipo de Recurso Azure-resource-type Selecione e configure quaisquer recursos adicionais exigidos pelo seu aplicativo.

  6. Depois que Visual Studio implantar seu projeto, crie o código para seu aplicativo.

Criar um arquivo OpenAPI (swagger) que descreva a API Web

Para conectar seu aplicativo de API Web a Power Automate, Power Apps ou Aplicativos Lógicos, você precisa de um arquivo OpenAPI (antigo Swagger) que descreva as operações da API. Você pode gravar sua própria definição da OpenAPI para sua API com o Editor online de Swagger, mas este tutorial usa uma ferramenta de código aberto chamada Swashbuckle.

  1. Caso ainda não tenha feito isso, instale o pacote Nuget do Swashbuckle em seu projeto de Visual Studio:

    1. Em Visual Studio, selecione Tools>NuGet Package Manager>Package Manager Console.

    2. No Package Manager Console, acesse o diretório de projeto do aplicativo se você ainda não estiver lá (execute Set-Location "project-path") e execute este cmdlet do PowerShell:

      Install-Package Swashbuckle

      Screenshot mostrando o Swashbuckle instalado pelo Console do Gerenciador de Pacotes.

    Dica

    Se você executar seu aplicativo depois de instalar o Swashbuckle, o Swashbuckle gerará um arquivo OpenAPI nesta URL:

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

    O Swashbuckle também gera uma interface de usuário nesta URL:

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

  2. Quando estiver pronto, publique seu aplicativo de API Web para Azure. Para publicar no Visual Studio, clique com o botão direito do mouse no projeto Web no Solution Explorer, selecione Publish e siga os prompts.

    Importante

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

    Se você usou o modelo C# de amostra, poderá corrigir esse problema alterando uma instância de ID de operação para Value_Get, e republicando.

  3. Obtenha o documento OpenAPI navegando até este local:

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

    Você também pode baixar um documento OpenAPI de exemplo neste tutorial. Certifique-se de remover os comentários, que começam com //, antes de usar o documento.

  4. Salve o conteúdo como um arquivo JSON. Dependendo do seu navegador, poderá ser necessário copiar e colar o texto em um arquivo de texto vazio.

Configurar a autenticação Microsoft Entra ID

Agora você cria dois aplicativos Microsoft Entra ID no Azure. Para saber mais, acesse Agração de aplicativos com Microsoft Entra ID.

Importante

Ambos os aplicativos devem estar no mesmo diretório.

Primeiro aplicativo Microsoft Entra ID: Protegendo a API Web

O primeiro aplicativo Microsoft Entra ID é usado para proteger a API Web. Nomeie-o como webAPI. Você pode habilitar a autenticação do Microsoft Entra ID em sua API Web seguindo estas etapas com os seguintes valores:

  • URL de login: https://login.windows.net
  • URL de resposta: https://<your-root-url>/.auth/login/aad/callback
  • Você não precisa de uma chave do cliente.
  • Você não precisa delegar nenhuma permissão.
  • Copie a ID do aplicativo, pois você precisará dele mais tarde.

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

O segundo aplicativo Microsoft Entra ID é usado para proteger o registro do conector personalizado e adquirir acesso delegado à API Web protegida pelo primeiro aplicativo. Nomeie-o como webAPI customAPI .

  • URL de login: https://login.windows.net
  • URL de resposta: https://msmanaged-na.consent.azure-apim.net/redirect
  • Adicione permissões para ter acesso delegado à API Web.
  • Copie a ID do aplicativo, pois você precisará dele mais tarde.
  • Gere uma chave de cliente e copie-a, porque você precisará dela mais tarde.

Adicionar autenticação ao seu aplicativo Web Azure

  1. Entre no Azure portal e localize o aplicativo Web que você implantou na primeira seção.

  2. Selecione Configurações e selecione Autenticação/Autorização.

  3. Ative App Service Authentication e selecione Azure Active Directory. Na próxima folha, selecione Expresso.

  4. Selecione Select Existing AD App e selecione o aplicativo webAPI Microsoft Entra ID criado anteriormente.

Agora você deve ser capaz de usar Microsoft Entra ID para autenticar seu aplicativo 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 usada para o aplicativo web. A seção de seu OpenAPI com a propriedade host deve ter esta aparência:
// 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...

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

  2. Depois de carregar o seu OpenAPI, o assistente detecta automaticamente que você está usando a autenticação do Microsoft Entra ID para a sua API Web.

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

  • ID do cliente: ID do cliente de webAPI-CustomAPI
  • Segredo do cliente: chave do cliente da WebAPI-CustomAPI
  • URL de logon: https://login.windows.net
  • ResourceUri: ID de cliente de webAPI
  1. Selecione Criar para criar uma conexão com o conector personalizado.

Importante

Se o conector usar o OAuth, é importante monitorar e renovar regularmente a ID do cliente expirada e as credenciais de segredo do cliente para que os clientes possam continuar usando o conector. Certifique-se de enviar a atualização do conector um mês antes da data em que a ID do cliente e o segredo do cliente estão definidos para expirar.

Saiba mais sobre a autenticação do Microsoft Entra ID

Faça 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.

  • Last updated on