Partilhar via

Auto-hospede seu portal do Centro de API

  • Artigo

Este artigo apresenta 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.

Captura de ecrã do portal do Centro de API após o início de sessão do utilizador.

Sobre o portal do Centro de API

O portal do Centro de API é um site que você pode criar e hospedar para exibir o inventário de API em seu centro de API. O portal permite que desenvolvedores e outras partes interessadas em sua organização descubram APIs e visualizem detalhes da API.

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. O acesso do usuário às informações da API é baseado no controle de acesso baseado em função do Azure.

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 registro de aplicativo em um locatário do Microsoft Entra associado à sua assinatura do Azure e permissões para conceder acesso aos dados em sua central 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:

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.

  1. No portal do Azure, navegue até Registros do Microsoft Entra ID>App.

  2. Selecione + Novo registo.

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

    • Defina Name como um nome significativo, como api-center-portal

    • Em Tipos de conta suportados, selecione Contas neste diretório organizacional (Locatário único).

    • Em Redirecionar URI, selecione Aplicativo de página única (SPA) e defina o URI.

      • Para testes locais, defina o URI como https://localhost:5173.
      • Para produção, defina o URI como o URI da implantação do portal do Centro de APIs.

    • Selecione Registar.

  4. Na página Visão geral, copie a ID do aplicativo (cliente) e a ID do diretório (locatário). Você define esses valores ao criar o portal.

  5. Na página Permissões da API, selecione + Adicionar uma permissão.

    1. Na página Solicitar permissões de API, selecione a guia APIs que minha organização usa. Procure e selecione Centro de API do Azure. Você também pode pesquisar e selecionar o ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573do aplicativo.
    2. Na página Permissões de solicitação, selecione user_impersonation.
    3. Selecione Adicionar permissões.

    As permissões do Centro de API do Azure aparecem em Permissões configuradas.

    Captura de ecrã das permissões necessárias no registo da aplicação Microsoft Entra ID no portal.

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 public/config.json arquivo para apontar para o seu serviço. Atualize os valores no arquivo da seguinte maneira:

    • Substitua <service name> e <region> pelo nome do seu centro de API e da região onde ele foi implantado
    • 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.
    • Atualize o valor de title para um nome que você deseja que apareça no portal.
    {
  "dataApiHostName": "<service name>.data.<region>.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 iniciará o portal no modo de desenvolvimento em execução local:

    npm start

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

Implementar 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

Os usuários devem entrar para ver as APIs em seu centro de APIs. 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, com escopo para o centro de APIs.

Importante

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

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. Seguem-se breves passos:

  1. No portal do Azure, navegue até o centro de APIs.
  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:
    • Na página Função, procure e selecione Leitor de Dados do Centro de API do Azure. Selecione Seguinte.
    • Na página Membros, em Atribuir acesso a, selecione Usuário, grupo ou entidade> de serviço+ Selecionar membros.
    • 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 Avançar.
    • Reveja a atribuição de função e selecione Rever + atribuir.

Nota

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âmico. Para saber mais, consulte Criar ou atualizar um grupo dinâmico no Microsoft Entra ID.

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

Nota

O primeiro usuário a entrar no portal é solicitado a consentir com as permissões solicitadas pelo registro do aplicativo do portal da Central de APIs. 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"

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údos relacionados