Hospede localmente o seu portal do Centro de API

Este artigo mostra como hospedar automaticamente o portal do Centro de APIs, um site que os desenvolvedores e outras partes interessadas em sua organização podem usar para descobrir as APIs em seu Centro de APIs. Implante uma implementação de referência do portal a partir do repositório inicial do portal do Centro de APIs .

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 APIs . O portal usa a API do plano de dados do Centro de API do Azure 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 as Ações do GitHub
• Uma plataforma de portal que os clientes podem modificar ou estender para atender às suas necessidades
• Flexibilidade para hospedar em diferentes infraestruturas, incluindo implantação em serviços como Aplicativos Web Estáticos do Azure.

Pré-requisitos

• Um centro de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API.

• Permissões para criar um registo de aplicação num tenant do Microsoft Entra associado à sua subscrição do Azure e permissões para conceder acesso aos dados no seu centro de APIs.

• Para criar e implantar o portal, você precisa de uma conta do GitHub e das seguintes ferramentas instaladas em sua máquina local:

  • Node.js e npm
  • Pacote Vite

Criar registo da aplicação Microsoft Entra

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

A Central de APIs pode configurar o registro do aplicativo automaticamente ou você pode criar o registro do aplicativo manualmente.

Configurar o registo da aplicação automaticamente

Para configurar o registo da aplicação automaticamente, siga estes passos:

1. No portal do Azure, navegue até o seu centro de API.
2. No menu à esquerda, selecione Configurações do portal> da Central deAPIs.
3. Na guia Provedor de identidade , selecione Iniciar configuração.
4. Na guia Configuração rápida , selecione Salvar + publicar.

Se precisar de aceder ao registo da aplicação mais tarde, pode encontrá-la no portal em Registos da aplicação. O aplicativo é nomeado com o seguinte formato: <api-center-name-apic-aad>.

Configurar o registo da aplicação manualmente

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

1. No portal do Azure, navegue até Microsoft Entra ID>Gerir>Registos de Aplicativos.

2. Selecione + Novo registo.

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

   1. Defina Name como um nome significativo, como api-center-portal
   2. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional (<Nome do diretório> - Locatário único).
   3. Em Redirecionar URI, selecione Aplicativo de página única (SPA) e defina o URI. Insira o URI da implantação do portal do Centro de APIs, no seguinte formato: https://<service-name>.portal.<location>.azure-apicenter.ms. Substitua <service name> e <location> pelo nome do seu centro de API e o local onde ele foi implantado, Exemplo: https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Selecione Register.

Configurar URIs de redirecionamento adicionais para extensão VS Code

Ao habilitar a exibição do portal da Central de APIs na extensão de código do Visual Studio para a Central de APIs, configure também os seguintes URIs de redirecionamento no registro do aplicativo:

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

2. Na página Gerir>Autenticação , selecione Adicionar uma plataforma e selecione Aplicações móveis e de ambiente de trabalho.

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

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

Configurar 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 em sua máquina local.

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

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

   cd APICenter-Portal-Starter
   

3. Confira o ramo 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 seu serviço. Atualize os valores no arquivo da seguinte maneira:

   1. Substitua <service name> e <location> pelo nome do seu centro de API e o local onde ele foi implantado
   2. Substitua <client ID> e <tenant ID> pelo ID do aplicativo (cliente) e 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 local:

   npm start
   

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

Distribuir no Azure

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

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

Para habilitar a entrada no portal do Centro de APIs para acessar APIs, atribua a função Leitor de Dados do Centro de API do Azure a usuários ou grupos em sua organização, com escopo para o centro de APIs.

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

1. No portal do Azure, navegue até o seu 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 forma:
   1. Na página Função , procure e selecione Leitor de Dados do Centro de API do Azure. Selecione Seguinte.
   2. Na página Membros, em Atribuir acesso a, selecione Usuário, grupo ou principal 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. Verifique a atribuição de função e selecione Verificar + atribuir.

Depois de configurar o acesso ao portal, os usuários configurados podem entrar no portal e exibir as APIs em seu centro de APIs.

Solução de problemas

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

Sob 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 em sua Central de APIs.

Se a função for atribuída ao usuário, 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 iniciar sessão no portal

Se os usuários aos quais foi atribuída a função de Leitor de Dados do Centro de API do Azure não puderem concluir o fluxo de entrada depois de selecionar Entrar no portal da Central de APIs, pode haver um problema com a configuração do provedor de identidade do Microsoft Entra ID.

No registro do aplicativo Microsoft Entra, revise 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 as permissões do Centro de API do Azure no registro do aplicativo Microsoft Entra

Se você não conseguir solicitar permissões de API para o Centro de API do Azure em seu registro de aplicativo Microsoft Entra para o portal do Centro de APIs, verifique se você está procurando por Central de API do Azure (ou ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573do aplicativo).

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 controlo de acesso baseado em funções (RBAC) do Azure?
• Práticas recomendadas para o RBAC do Azure
• Registrar um provedor de recursos