Partilhar via


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

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

Gorjeta

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

Pré-requisitos

Para administradores do centro de API

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

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

    Importante

    Atualmente, o acesso ao catálogo da API da 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 de 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 visualização Extensões.

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

  • Extensão Microsoft Kiota - para gerar clientes API

Etapas para os 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 da API da plataforma.

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 a extensão de código do Visual Studio para o Centro de API do Azure acesse o catálogo de API da plataforma 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 platform-api-catalog
    • 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 como o URI de tempo de execução do seu centro de API. Por exemplo, https://<service name>.data.<region>.azure-apicenter.ms. Exemplo: https://contoso-apic.data.eastus.azure-apicenter.ms.
    • Selecione Registar.

    Gorjeta

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

  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 mais tarde quando você se conecta ao centro de API a partir da extensão de código do Visual Studio.

  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> de API+ Adicionar uma permissão.

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

    1. Selecione a guia APIs que minha organização usa .
    2. Procure e selecione Centro de API do Azure. Você também pode pesquisar e selecionar o ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573do 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 ecrã das permissões necessárias no registo da aplicação Microsoft Entra ID no portal.

Habilitar o login no catálogo de API da plataforma por usuários e grupos do Microsoft Entra

Os programadores empresariais têm de iniciar sessão com uma conta Microsoft para ver o catálogo de API da plataforma para o seu centro de API. Se necessário, adicione ou convide desenvolvedores para seu locatário do Microsoft Entra.

Em seguida, para habilitar o login, atribua a função Leitor de Dados do Centro de API do Azure a usuários ou grupos em seu locatário, com escopo para sua Central de APIs.

Importante

Por padrão, você e outros administradores do centro de API não têm acesso às APIs no catálogo de API da plataforma da extensão 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.
  4. Repita as etapas anteriores para habilitar o login no catálogo de API da plataforma para mais centros de API.

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.

Etapas para desenvolvedores corporativos acessarem o catálogo da API da plataforma

Os desenvolvedores podem seguir estas etapas para se conectar e entrar para exibir um catálogo de API de plataforma usando a extensão 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 for Visual Studio Code.

  2. No Visual Studio Code, na barra de atividades à esquerda, selecione Central de APIs.

    Captura de ecrã do ícone do Centro de API na Barra de Atividades.

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

  4. Responda às solicitações para inserir as seguintes informações:

    1. A URL de tempo de execução do seu 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 tempo de execução aparece na página Visão geral do centro de API no portal do Azure.
    2. O ID do aplicativo (cliente) do registro do aplicativo configurado pelo administrador na seção anterior.
    3. O ID do diretório (locatário) do registro do aplicativo configurado pelo administrador na seção anterior.

    Gorjeta

    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 aparece no catálogo de API da plataforma do Centro de API.

  5. Para exibir as APIs no centro de APIs, sob o nome do centro de APIs, selecione Entrar no Azure. O início de sessão é permitido com uma conta Microsoft à qual é atribuída a função de Leitor de Dados do Centro de API do Azure no Centro de API .

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

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

    Captura de tela do catálogo de API da plataforma API Center com APIs na extensão 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 API da plataforma ajuda os desenvolvedores corporativos a descobrir detalhes da API e iniciar o desenvolvimento do cliente da 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 API da plataforma:

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

Resolução de Problemas

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

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

Verifique se o usuário recebeu a função Leitor de Dados do Centro de API do Azure no Centro de APIs . Se necessário, reatribua a função ao usuário. Em seguida, atualize o catálogo de API da plataforma API Center na extensão Visual Studio Code.

Não é possível entrar no Azure

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 Azure no catálogo da API da plataforma, pode haver 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 do ID do aplicativo (cliente) e do ID do diretório (locatário) no registro do aplicativo e na URL de tempo de execução do centro de API. Em seguida, configure a conexão com o centro de API novamente.

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

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.