Compartilhar via

Auto-hospedar seu portal do Centro de API

  • Artigo

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

Captura de tela do portal do Centro de APIs após o login do usuário.

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 no centro de API. O portal permite que os desenvolvedores e outros stakeholders da sua organização descubram as APIs e vejam os detalhes da API.

Você pode criar e implantar uma implementação de referência do portal usando código do repositório inicial do portal do Centro de API. O portal usa a API do plano de dados do Centro de API do Azure para recuperar dados do centro de API. O acesso do usuário às informações da API baseia-se 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 por meio do GitHub Actions
  • Uma plataforma do portal que os clientes podem modificar ou estender para atender às respectivas necessidades
  • Flexibilidade para hospedagem em diferentes infraestruturas, incluindo a implantação em serviços como os Aplicativos Web Estáticos do Azure.

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

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

Criar um registro de aplicativo do Microsoft Entra

Primeiro, configure um registro de aplicativo no locatário 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.

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

  2. Selecione + Novo Registro.

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

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

    • Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional (locatário único).

    • Em URI de Redirecionamento, selecione SPA (aplicativo de página única) 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 API.

    • Selecione Registrar.

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

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

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

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

    Captura de tela das permissões necessárias no registro de aplicativos do 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 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. Faça check-out da ramificação principal.

    git checkout main

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

  5. Em seguida, edite o arquivo public/config.json para apontar para o serviço. Atualize os valores no arquivo conforme descrito a seguir:

    • Substitua <service name> e <region> pelo nome do centro de API e da região em que ele é implantado
    • Substitua <client ID> e <tenant ID> pela ID do Aplicativo (cliente) e pela 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 exibir 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. Instalar os pacotes necessários.

    npm install

  7. Inicie o Development Server. O seguinte comando iniciará o portal no modo de desenvolvimento em execução localmente:

    npm start

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

Implantar no Azure

Para ver as etapas necessárias para implantar o portal nos Aplicativos Web Estáticos do Azure, confira o repositório inicial do portal do Centro de API.

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

Os usuários precisam se conectar para ver as APIs no centro de API. Para habilitar a entrada, atribua a função Leitor de dados do centro de API do Azure a usuários ou grupos da sua organização, com escopo para o 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. Certifique-se de atribua a função Leitor de Dados do Centro de API do Azure a si mesmo e a outros administradores.

Para ver prerrequisitos 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:
    • Na página Função, pesquise e selecione Leitor de dados do centro de API do Azure. Selecione Avançar.
    • 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 Avançar.
    • 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 no Microsoft Entra ID.

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 serão solicitados a consentir.

Soluçã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 a função Leitor de dados do centro de API do Azure é atribuída ao usuário no centro de API.

Se a função for atribuída ao usuário, pode haver um problema com o registro do provedor de recursos Microsoft.ApiCenter na 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 foi possível entrar no portal

Se os usuários que receberam a função de Leitor de Dados do Centro de API do Azure não conseguirem concluir o fluxo de entrada depois de selecionar Entrar no portal do Centro de API, talvez ocorra um problema com a configuração do provedor de identidade do Microsoft Entra ID.

No registro de aplicativo do Microsoft Entra, revise e, se necessário, atualize as configurações do 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

Se não for possível solicitar permissões de API ao centro de API do Azure no registro de aplicativo do Microsoft Entra para o portal do centro de API, verifique se você está procurando o centro de API do Azure (ou a ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573 do aplicativo).

Se o aplicativo não estiver presente, pode haver um problema com o registro do provedor de recursos Microsoft.ApiCenter na 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.

Diretiva 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