Hospedar localmente seu portal do Centro de APIs

Este artigo mostra como hospedar automaticamente o portal do Centro de API, um site que os desenvolvedores e outros stakeholders da sua organização podem usar para descobrir as APIs em seu centro de API. Implante uma implementação de referência do portal no repositório inicial do portal do Centro de API .

Dica

Novo! Agora você pode configurar uma versão gerenciada pelo Azure do portal do Centro de API. Para obter mais informações, consulte Configurar o portal do Centro de API.

Sobre a auto-hospedagem do portal

Você pode criar e implantar uma implementação de referência do portal usando código no repositório inicial do portal do Centro de API . O portal usa a API do plano de dados do Azure API Center para recuperar dados do seu centro de API.

A implementação de referência do portal do Centro de API fornece:

• Uma estrutura para publicar e manter um portal de API gerenciado pelo cliente usando o GitHub Actions
• Uma plataforma do portal que os clientes podem modificar ou estender para atender às suas necessidades
• Flexibilidade para hospedar em diferentes infraestruturas, incluindo a implantação em serviços como Aplicativos Web Estáticos do Azure.

Observação

Ao hospedar automaticamente o portal do Centro de API, você se torna seu mantenedor e é responsável por suas atualizações. O suporte do Azure é limitado.

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.

• Permissões para criar uma inscrição de aplicativo em um tenant do Microsoft Entra associado à sua assinatura do Azure e permissões para conceder acesso aos dados na central de APIs.

• Para criar e implantar o portal, você precisa de uma conta do GitHub e das seguintes ferramentas instaladas no computador local:

  • Node e npm
  • Pacote do Vite

Criar registro de aplicativo do Microsoft Entra

Primeiro, configure um registro de aplicativo no seu tenant do Microsoft Entra ID. O registro do aplicativo permite que o portal do Centro de API acesse dados do centro de API em nome de um usuário conectado.

O Centro de API pode configurar o registro do aplicativo automaticamente ou você pode criar o registro do aplicativo manualmente.

Configurar o registro do aplicativo automaticamente

Para configurar o registro do aplicativo automaticamente, siga estas etapas:

1. No portal do Azure, navegue até o centro de API.
2. No menu à esquerda, selecioneConfigurações do portal > do Centro de API.
3. Na guia Provedor de identidade , selecione Iniciar configuração.
4. Selecione Salvar + publicar.

Configurar o registro do aplicativo manualmente

Se você quiser criar o registro do aplicativo manualmente, siga estas etapas:

1. No portal do Azure, navegue até Microsoft Entra ID>registros de aplicativos.

2. Selecione + Novo registro.

3. Na página Registrar um aplicativo, defina os valores da seguinte forma:

   1. Definir Nome como um nome significativo, como api-center-portal
   2. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional (locatário único).
   3. No URI de Redirecionamento, selecione SPA (aplicativo de página única) e defina o URI. Insira o URI da implantação do portal do Centro de API no seguinte formulário: https://<service-name>.portal.<location>.azure-api-center.ms. Substitua <service name> e <location> pelo nome do centro de API e o local onde ele é implantado, exemplo: https://myapicenter.portal.eastus.azure-api-center.ms.
   4. Selecione Registrar.

Configurar URIs de redirecionamento adicionais para a extensão do VS Code

Ao habilitar a exibição do portal do Centro de API na extensão do Visual Studio Code para o Centro de API, configure também as seguintes URIs de redirecionamento no registro do aplicativo:

1. No portal do Azure, navegue até o registro do aplicativo.

2. Na página Gerenciar>Autenticação , selecione Adicionar uma plataforma e selecione Aplicativos móveis e de área de trabalho.

3. Configure as seguintes três URIs de redirecionamento personalizadas:
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Substitua <application-client-id> pelo ID do cliente deste aplicativo. Você pode encontrar esse valor na página Visão geral do registro do aplicativo.

Observação

Quando você estiver hospedando o portal automaticamente e quiser testá-lo localmente antes de implantar no Azure, defina o URI de redirecionamento no registro do aplicativo como https://localhost:5173.

Configurar o ambiente local

Siga estas etapas para criar e testar o portal do Centro de API localmente.

1. Clone o repositório inicial do portal do Centro de API no computador local.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. Altere para o diretório APICenter-Portal-Starter.

   cd APICenter-Portal-Starter
   

3. Confira a ramificação principal.

   git checkout main
   

4. Para configurar o serviço, copie ou renomeie o public/config.example arquivo para public/config.json.

5. Em seguida, edite o arquivo public/config.json para apontar para o serviço. Atualize os valores no arquivo da seguinte maneira:

   1. Substitua <service name> e <location> pelo nome do centro de API e o local em que ele é implantado
   2. Substitua <client ID> e <tenant ID> pela ID do aplicativo (cliente) e a ID do diretório (locatário) do registro do aplicativo que você criou na seção anterior.
   3. Atualize o valor de title para um nome que você deseja que apareça na barra superior do portal.

   {
     "dataApiHostName": "<service name>.data.<location>.azure-apicenter.ms/workspaces/default",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/user_impersonation"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. Instale os pacotes necessários.

   npm install
   

7. Inicie o servidor de desenvolvimento. O comando a seguir inicia o portal no modo de desenvolvimento em execução localmente:

   npm start
   

   Navegue até o portal em https://localhost:5173.

Publicar no Azure

Para obter etapas para implantar o portal nos Aplicativos Web Estáticos do Azure, consulte o repositório inicial do portal do Centro de API .

Habilitar a entrada no portal por usuários e grupos do Microsoft Entra

Para habilitar o login, atribua a função Leitor de Dados do Centro de API do Azure a usuários ou grupos em sua organização, limitada ao seu centro de API.

Importante

Por padrão, você e outros administradores do centro de API não têm acesso a APIs no portal do Centro de API. Atribua a função Leitor de Dados do Centro de API do Azure a si mesmo e a outros administradores.

Para obter pré-requisitos e etapas detalhados para atribuir uma função a usuários e grupos, consulte Atribuir funções do Azure usando o portal do Azure. Etapas breves a seguir:

1. No portal do Azure, navegue até o centro de API.
2. No menu à esquerda, selecione Controle de acesso (IAM)>+ Adicionar atribuição de função.
3. No painel Adicionar atribuição de função , defina os valores da seguinte maneira:
   1. Na página Função , pesquise e selecione Leitor de Dados do Centro de API do Azure. Selecione Próximo.
   2. Na página Membros, em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço>+ Selecionar membros.
   3. Na página Selecionar membros, pesquise e selecione os usuários ou grupos aos quais atribuir a função. Clique em Selecionar e, em seguida, em Seguinte.
   4. Examine a atribuição de função e selecione Examinar + atribuir.

Observação

Para simplificar a configuração de acesso para novos usuários, recomendamos que você atribua a função a um grupo do Microsoft Entra e configure uma regra de associação de grupo dinâmica. Para saber mais, consulte Criar ou atualizar um grupo dinâmico na ID do Microsoft Entra.

Depois de configurar o acesso ao portal, os usuários configurados poderão entrar no portal e exibir as APIs no centro de API.

Observação

O primeiro usuário a entrar no portal é solicitado a consentir com as permissões solicitadas pelo registro de aplicativo do portal do Centro de API. Depois disso, outros usuários configurados não são solicitados a consentir.

Resolução de problemas

Erro: "Você não está autorizado a acessar este portal"

Em determinadas condições, um usuário pode encontrar a seguinte mensagem de erro depois de entrar no portal do Centro de API com uma conta de usuário configurada:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Primeiro, confirme se o usuário recebeu a função leitor de dados do Centro de API do Azure no centro de API.

Se o usuário receber a função, pode haver um problema com o registro do provedor de recursos Microsoft.ApiCenter em sua assinatura e talvez seja necessário registrar novamente o provedor de recursos. Para fazer isso, execute o seguinte comando na CLI do Azure:

az provider register --namespace Microsoft.ApiCenter

Não é possível entrar no portal

Se os usuários que receberam a função leitor de dados do Centro de API do Azure não puderem concluir o fluxo de entrada depois de selecionar entrar no portal do Centro de API, pode haver um problema com a configuração do provedor de identidade do Microsoft Entra ID.

No registro do aplicativo Microsoft Entra, examine e, se necessário, atualize as configurações de URI de Redirecionamento para garantir que o URI corresponda ao URI da implantação do portal do Centro de API.

Não é possível selecionar permissões do Centro de API do Azure no registro de aplicativo do Microsoft Entra

Caso você não consiga solicitar permissões de API para o Centro de API do Azure no registro de aplicativo no Microsoft Entra para o portal do Centro de API, verifique se está pesquisando pelo Centro de API do Azure (ou ID do aplicativo c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Se o aplicativo não estiver presente, pode haver um problema com o registro do provedor de recursos Microsoft.ApiCenter em sua assinatura. Talvez seja necessário registrar novamente o provedor de recursos. Para fazer isso, execute o seguinte comando na CLI do Azure:

az provider register --namespace Microsoft.ApiCenter

Depois de registrar novamente o provedor de recursos, tente novamente solicitar permissões de API.

Política de suporte

Forneça comentários, solicite recursos e obtenha suporte para a implementação de referência do portal do Centro de API no repositório inicial do portal do Centro de API .

Conteúdo relacionado

• Configurar o portal do Centro de API
• O que é o RBAC (controle de acesso baseado em função) do Azure?
• Práticas Recomendadas para RBAC do Azure
• Registrar um provedor de recursos