Compartilhar via

Habilitar e exibir o catálogo de APIs de plataforma do Centro de API do Azure

  • Artigo

Este artigo mostra como fornecer aos desenvolvedores corporativos acesso ao catálogo de APIs de plataforma do Centro de API do Azure (versão prévia) na extensão do Visual Studio Code para o Centro de API do Azure. Usando o catálogo de APIs de plataforma, os desenvolvedores podem descobrir APIs no Centro de API do Azure, exibir definições de API e, opcionalmente, gerar clientes de API quando não tiverem acesso para gerenciar o centro de API propriamente dito ou adicionar APIs ao inventário. O acesso ao catálogo de APIs de plataforma é gerenciado usando o Microsoft Entra ID e o controle de acesso baseado em função do Azure.

Dica

A extensão do Visual Studio Code fornece mais recursos para desenvolvedores de API que têm permissões para gerenciar um centro de API do Azure. Por exemplo, os desenvolvedores de API podem registrar APIs no centro de API diretamente ou usando pipelines de CI/CD. Saiba mais

Pré-requisitos

Para administradores do centro de API

  • 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 desenvolvedores de aplicativos

  • Extensão do Centro de API do Azure para Visual Studio Code

    Importante

    Atualmente, o acesso ao catálogo de APIs de plataforma está disponível apenas na versão de pré-lançamento da extensão. Ao instalar a extensão do Visual Studio Code Marketplace, você pode optar por instalar a versão de lançamento ou uma versão pré-lançamento. Alterne entre as duas versões a qualquer momento usando o menu de contexto do botão Gerenciar da extensão na exibição de Extensões.

A seguinte extensão do Visual Studio Code é opcional:

Etapas para administradores do centro de API habilitarem o acesso ao catálogo

As seções a seguir fornecem etapas para que os administradores do centro de API permitam que os desenvolvedores corporativos acessem o catálogo de APIs de plataforma.

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 a extensão do Visual Studio Code para o Centro de API do Azure acesse o catálogo de APIs de plataforma 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 platform-api-catalog.
    • Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional (locatário único).
    • No URI de Redirecionamento, selecione SPA (aplicativo de página única) e defina o URI como o URI de runtime do centro de API. Por exemplo, https://<service name>.data.<region>.azure-apicenter.ms. Exemplo: https://contoso-apic.data.eastus.azure-apicenter.ms.
    • Selecione Registrar.

    Dica

    Você pode usar o mesmo registro de aplicativo para acessar mais centros de API. No URI de Redirecionamento, continue a adicionar URIs de redirecionamento para outros centros de API que você deseja que apareçam no catálogo de APIs de plataforma.

  4. Na página Visão geral, copie a ID do Aplicativo (cliente) e a ID do Diretório (locatário). Defina esses valores posteriormente quando se conectar ao centro de API da extensão do Visual Studio Code.

  5. No menu à esquerda, em Gerenciar, selecione Autenticação>+ Adicionar uma plataforma.

  6. Na página Configurar plataformas, selecione Aplicativos móveis e de desktop.

  7. Na página Configurar Área de Trabalho + dispositivos, insira o seguinte URI de redirecionamento e selecione Configurar:

    https://vscode.dev/redirect

  8. No menu à esquerda, em Gerenciar, selecione Permissões da API>+ Adicionar uma permissão.

  9. Na página Solicitar permissões de API, faça o seguinte:

    1. Selecione a guia APIs que a minha organização usa.
    2. 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.
    3. Na página Selecionar permissões, selecione user_impersonation.
    4. 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.

Habilitar a entrada no catálogo de APIs de plataforma por usuários e grupos do Microsoft Entra

Os desenvolvedores corporativos precisam entrar com uma conta Microsoft para ver o catálogo de APIs de plataforma do centro de API. Se necessário, adicione ou convide desenvolvedores ao seu locatário do Microsoft Entra.

Depois, para habilitar a entrada, atribua a função Leitor de dados do centro de API do Azure a usuários ou grupos no seu locatário, 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 catálogo de APIs de plataforma da extensão 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.
  4. Repita as etapas anteriores para habilitar a entrada no catálogo de APIs de plataforma para mais centros de API.

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.

Etapas para os desenvolvedores corporativos acessarem o catálogo de APIs de plataforma

Os desenvolvedores podem seguir estas etapas para se conectarem e entrarem para exibir um catálogo de APIs de plataforma usando a extensão do Visual Studio Code. As configurações para se conectar ao centro de API precisam ser fornecidas pelo administrador do centro de API.

Conectar-se a um centro de API

  1. Instale a versão de pré-lançamento da extensão do Centro de API do Azure para Visual Studio Code para Visual Studio Code.

  2. No Visual Studio Code, na Barra de Atividades à esquerda, selecione Centro de API.

    Captura de tela do ícone de Centro de API na Barra de Atividades.

  3. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: conecte-se a um Centro de API e pressione Enter.

  4. Responda aos prompts para inserir as seguintes informações:

    1. A URL de runtime do centro de API, no formato <service name>.data.<region>.azure-apicenter.ms (não prefixe com https://). Exemplo: contoso-apic.data.eastus.azure-apicenter.ms. Essa URL de runtime aparece na página Visão geral do centro de API no portal do Azure.
    2. A ID do aplicativo (cliente) do registro do aplicativo configurado pelo administrador na seção anterior.
    3. A ID do diretório (locatário) do registro do aplicativo configurado pelo administrador na seção anterior.

    Dica

    Um administrador do centro de API precisa fornecer esses detalhes de conexão aos desenvolvedores ou fornecer um link direto no seguinte formato:
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    Depois de se conectar ao centro de API, o nome do centro de API será exibido no catálogo de APIs de plataforma do Centro de API.

  5. Para exibir as APIs no centro de API, no nome do centro de API, selecione Entrar no Azure. A entrada é permitida com uma conta Microsoft que recebe a função Leitor de Dados do Centro de API do Azure no centro de API.

    Captura de tela do catálogo de APIs de plataforma do Centro de API na extensão do VS Code.

  6. Depois de entrar, selecione APIs para listar as APIs no centro de API. Expanda uma API para explorar as versões e definições dela.

    Captura de tela do catálogo de APIs de plataforma do Centro de API com APIs na extensão do VS Code.

  7. Repita as etapas anteriores para se conectar a mais centros de API, se o acesso estiver configurado.

Descobrir e consumir APIs no catálogo

O catálogo de APIs de plataforma ajuda os desenvolvedores corporativos a descobrir detalhes da API e iniciar o desenvolvimento do cliente de API. Os desenvolvedores podem acessar os seguintes recursos clicando com o botão direito do mouse em uma definição de API no catálogo de APIs de plataforma:

  • Exportar um documento de especificação de API – exporte uma especificação de API de uma definição e depois baixe-a como um arquivo
  • Gerar cliente de API – Use a extensão do Microsoft Kiota para gerar um cliente de API para o idioma favorito deles
  • Gerar Markdown – Gerar documentação da API no formato Markdown
  • Documentação de OpenAPI – Veja a documentação de uma definição de API e experimente as operações em uma interface do usuário do Swagger (disponível apenas para definições de OpenAPI)

Solução de problemas

Em determinadas condições, um usuário pode encontrar a seguinte mensagem de erro depois de entrar no catálogo de APIs de plataforma do Centro de API e expandir a lista de APIs para um centro de API:

Error: Cannot read properties of undefined (reading 'nextLink')

Confirme se a função Leitor de dados do centro de API do Azure é atribuída ao usuário no centro de API. Se necessário, reatribua a função ao usuário. Em seguida, atualize o catálogo de APIs de plataforma do Centro de API na extensão do Visual Studio Code.

Não foi possível entrar no Azure

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 Azure no catálogo de APIs da plataforma, talvez haja um problema com a configuração da conexão.

Verifique as configurações no registro do aplicativo que você configurou no Microsoft Entra ID. Confirme os valores da ID do aplicativo (cliente) e a ID do diretório (locatário) no registro do aplicativo e na URL de runtime do centro de API. Em seguida, configure a conexão com o centro de API novamente.

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

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.

Conteúdo relacionado