Compartilhar via

Criar um conector personalizado para uma API Web

  • Artigo

Este tutorial mostra como começar a criar uma API Web ASP.NET, hospedá-la no recurso Aplicativos Web do Azure do Serviço de Aplicativo do Azure, habilitar a autenticação do Microsoft Entra ID e registrar a API Web ASP.NET no Power Automate. Depois de a API ser registrada, você pode conectá-la e chamá-la a partir de seu fluxo. Você também pode registrar e chamar a API a partir do Power Apps ou dos Aplicativos Lógicos do Azure.

Pré-requisitos

Criar e implantar um aplicativo Web ASP.NET no Azure

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

  1. Abra o Visual Studio e selecione Arquivo > Novo Projeto.

    1. Expanda Instalado, vá para Modelos > Visual C# > Web e selecione Aplicativo Web ASP.NET.

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

    Captura de tela mostrando um novo aplicativo Web Visual C#ASP.NET.

  2. Na caixa Novo Aplicativo da Web ASP.NET, selecione o modelo API Web, certifique-se de que a caixa de seleção Hospedar na nuvem está marcada e, em seguida, selecione Alterar Autenticação.

    Captura de tela mostrando o 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 Novo aplicativo Web ASP.NET for reexibida, 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 do Serviço de Aplicativo representa uma coleção de recursos físicos usados para hospedar aplicativos na sua assinatura do 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 do 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.
    Assinatura Azure-subscription-name Selecione a assinatura do Azure que deseja usar.
    Grupo de Recursos Azure-resource-group-name Selecione um grupo de recursos existente do Azure ou, se ainda não fez isso, crie um grupo de recursos.

    Observação: um grupo de recursos do Azure organiza os 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
    Location deployment-region Selecione a região para implantar seu aplicativo.
    Tamanho App-Service-plan-size 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 necessários ao seu aplicativo, selecione Explorar serviços adicionais do Azure.

    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 o Visual Studio implanta 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 ao Power Automate, Power Apps ou Aplicativos Lógicos, é preciso um arquivo OpenAPI (antes conhecido como Swagger) que descreve 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. Se ainda não fez isso, instale o pacote do Swashbuckle Nuget no seu projeto do Visual Studio:

    1. No Visual Studio, selecione Ferramentas > Gerenciador de Pacotes NuGet > Console do Gerenciador de Pacotes.

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

      Install-Package Swashbuckle

      Captura de tela mostrando o Swashbuckle instalado usando o 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 no Azure. Para publicar no Visual Studio, clique com o botão direito do mouse no seu projeto Web no Solution Explorer, escolha Publicar e siga as instruções.

    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 do Microsoft Entra ID

Agora você criará dois aplicativos do Microsoft Entra ID no Azure. Para saber mais, acesse Integrando aplicativos com o Microsoft Entra ID.

Importante

Ambos os aplicativos devem estar no mesmo diretório.

Primeiro aplicativo do Microsoft Entra ID: proteção da API Web

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

  • URL de entrada: 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.

Segundo aplicativo do Microsoft Entra ID: proteção do conector personalizado e acesso delegado

O segundo aplicativo do 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 entrada: 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 aplicativo Web do Azure

  1. Entre no portal do Azure e localize o aplicativo Web implantado na primeira seção.

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

  3. Ative Autenticação de serviço de aplicativo e depois selecione Azure Active Directory. Na próxima folha, selecione Expresso.

  4. Selecione Selecionar Aplicativo Existente do AD e selecione a webAPI do aplicativo do Microsoft Entra ID que você criou anteriormente.

Agora, você poderá usar o Microsoft Entra ID para autenticar seu aplicativo Web.

Adicionar o conector personalizado ao Power Automate

  1. Modifique a 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 Usar conectores personalizados no Power Automate.

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

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

  • ID do cliente: ID do cliente de webAPI-CustomAPI
  • Segredo: chave do cliente de 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.

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

Enviar 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.