Partilhar via

Habilite a análise de API em seu centro de API - autogerenciado

Este artigo explica como ativar a análise de APIs no Azure API Center para configurar um motor de lintagem e ativadores. Esses recursos analisam suas definições de API para aderência às regras de estilo organizacional, gerando relatórios individuais e resumidos. A análise de API ajuda a identificar e corrigir erros comuns e inconsistências em suas definições de API.

Os procedimentos seguintes suportam a implementação automatizada da ferramenta de linting e da assinatura de eventos no seu centro de API. Use o CLI do Azure Developer (azd) para um desdobramento em um único passo da infraestrutura de linting, proporcionando um processo de implementação simplificado. Os exemplos de comandos Azure CLI podem correr em PowerShell ou numa shell bash. São fornecidos exemplos de comandos separados, conforme necessário.

Se preferir configurar o motor de aplicações e os recursos através de implementação manual, consulte o repositório Azure API Center Analyzer GitHub para orientações sobre como implementar a função da aplicação e configurar a subscrição do evento.

Nota

O Centro de API do Azure também configura automaticamente um motor de linting padrão e dependências para análise de API. Se habilitar a análise autogerenciada conforme descrito neste artigo, substituirá esses recursos incorporados.

Descrição geral do cenário

Nesse cenário, analisas as definições de API no teu centro de API usando o motor de linting open source Spectral. Uma aplicação de funções construída com o Azure Functions executa o motor de linting em resposta a eventos no seu centro de API. O Spectral verifica se as APIs definidas em um documento de especificação JSON ou YAML estão em conformidade com as regras em um guia de estilo de API personalizável. É gerado um relatório de análise que pode ser visualizado no seu centro de API.

O diagrama a seguir mostra as etapas para habilitar o linting e a análise no centro de API.

Diagrama que mostra como funciona o API linting no Azure API Center.

  1. Implemente uma aplicação de funções que execute o motor de linting Spectral numa definição de API.

  2. Configura uma subscrição de evento num centro de API do Azure que acione a aplicação de funções.

  3. Um evento é acionado pela adição ou substituição de uma definição de API no centro de API.

  4. Ao receber o evento, a aplicação de funções invoca o motor de linting Spectral.

  5. O motor de linting verifica se as APIs definidas na especificação estão em conformidade com o manual de estilo de API da organização e gera um relatório.

  6. Exiba o relatório de análise no centro de API.

Limitações

  • Atualmente, o Linting suporta apenas arquivos de especificação JSON ou YAML, como documentos de especificação OpenAPI ou AsyncAPI.

  • Por padrão, a ferramenta de lint usa o conjunto de regras interno. Para expandir o conjunto de regras ou criar guias de estilo personalizados para APIs, consulte o repositório Spectral no GitHub.

  • A aplicação de funções que invoca o linting é carregada separadamente, e tu geres e mantém essa aplicação.

Pré-requisitos

  • Um centro de API na sua subscrição do Azure. Para criar uma subscrição, consulte Quickstart: Criar o seu centro de API.

  • O fornecedor de recursos da Grade de Eventos registado na sua subscrição. Se precisar de registar o fornecedor de recursos da Grelha de Eventos, consulte Subscrever eventos publicados por um parceiro com a Grelha de Eventos do Azure.

  • Azure Developer CLI (azd). Instale azd na sua máquina no ambiente que planeia usar para o procedimento seguinte.

  • Ferramentas de Núcleo do Azure Functions. Instale as ferramentas essenciais da sua máquina no ambiente que planeia usar para o procedimento seguinte. Certifica-te de que as ferramentas estão acessíveis pelas tuas PATH definições.

  • Para a CLI do Azure:

    Nota

    Os az apic comandos requerem a apic-extension extensão Azure CLI. A extensão pode ser instalada dinamicamente quando executa o seu primeiro az apic comando, ou pode instalá-la manualmente. Para mais informações, consulte Gerir Extensões de CLI Azure: Instalar, Atualizar e Remover.

    Para ver as últimas alterações e atualizações no apic-extension, consulte as notas de lançamento. Certas funcionalidades podem exigir uma pré-visualização ou uma versão específica da extensão.

Utilize a implementação azd para funções e subscrição de eventos

Os procedimentos seguintes fornecem passos automatizados para o Azure Developer CLI (azd) configurar aplicação de funções e subscrição de eventos que permitam linting e análise no seu centro de API.

Nota

Se preferires configurar o motor e os recursos com implementação manual, consulta o repositório GitHub do Azure API Center Analyzer para orientações sobre como implementar a aplicação de funções e configurar a subscrição do evento.

Executa a amostra usando azd

  1. Clone o repositório de exemplo Azure API Center Analyzer no GitHub para a sua máquina local.

  2. Inicie o Visual Studio Code e selecione Ficheiro>Abrir Pasta (Ctrl+K, Ctrl+O). Navegue até à APICenter-Analyzer pasta do repositório clonado e escolha a pasta Select.

  3. Na Barra de Atividades de Código do Visual Studio, selecione Explorer (Ctrl+Shift+E) para poderes ver a estrutura das pastas do repositório.

    • Expanda a resources/rulesets pasta e observe o oas.yaml ficheiro. Este ficheiro reflete o seu guia de estilo atual da API. Pode modificar este ficheiro para satisfazer as necessidades da sua organização.

    • Expanda a src/functions pasta e observe o ApiAnalyzerFunction.ts ficheiro. Este ficheiro fornece o código da função da aplicação de funções. Pode modificar este ficheiro para ajustar o comportamento da função para cumprir os requisitos da sua aplicação.

  4. Abra um terminal no Visual Studio Code e autentique com o Azure Developer CLI (azd):

    azd auth login

    Sugestão

    Pode evitar problemas de autenticação em ambientes de desenvolvimento executando os seguintes comandos:

    1. Crie um novo ambiente de desenvolvimento: azd env new
    2. Obtenha o seu ID de inquilino: az account show --query tenantId -o tsv (copie o ID de saída para mais tarde)
    3. Terminar sessão: azd auth logout comando
    4. Inicie sessão em azd utilizando o valor tenantId do passo 2: azd auth login --tenant-id <tenant_ID>

    Quando autenticas com sucesso, a saída do comando mostra-te Logado no Azure como <your_user_alias>.

  5. De seguida, inicie sessão no portal Azure usando a CLI do Azure:

    az login

    É solicitado que introduza as suas credenciais para iniciar sessão no Azure.

    Uma janela do navegador confirma o seu início de sessão bem-sucedido. Feche a janela e volte a este procedimento.

  6. Execute o seguinte comando para disponibilizar a infraestrutura de linting na sua subscrição do Azure.

    Para este comando, precisa da seguinte informação. A maioria destes valores está disponível na página de Visão Geral do seu recurso do centro API no portal Azure.

    • Nome e ID da subscrição
    • Nome do centro API
    • Nome do grupo de recursos para o centro API
    • Região de implementação para a aplicação de funções (pode ser diferente da região do centro da tua API)
    azd up

  7. Siga os prompts para fornecer a informação e definições necessárias para a implementação. Para mais informações, veja Executar o exemplo usando a CLI Azure Developer (azd).

    À medida que a implementação avança, o resultado mostra as tarefas de provisionamento concluídas:

    Nota

    Pode demorar vários minutos a provisionar a aplicação de funções e a implementá-la no Azure.

    Packaging services (azd package)

(✓) Done: Packaging service function
- Build Output: C:\GitHub\APICenter-Analyzer
- Package Output: C:\Users\<user>\AppData\Local\Temp\api-center-analyzer-function-azddeploy-0123456789.zip

Loading azd .env file from current environment

Provisioning Azure resources (azd provision)
Provisioning Azure resources can take some time.

Subscription: <your_selected_subscription>
Location: <your_selected_region_for_this_process>

You can view detailed progress in the Azure Portal:

https://portal.azure.com/#view/HubsExtension/DeploymentDetailsBlade/~/overview/id/%2Fsubscriptions%2F00001111-a2a2-b3b3-c4c4-dddddd555555%2Fproviders%2FMicrosoft.Resources%2Fdeployments%2F<your_azd_environment_name-0123456789>

(✓) Done: Resource group: <new_resource_group_for_function_app> (5.494s)
(✓) Done: App Service plan: <new_app_service_plan> (5.414s)
(✓) Done: Storage account: <new_storage_account> (25.918s)
(✓) Done: Log Analytics workspace: <new_workspace> (25.25s)
(✓) Done: Application Insights: <new_application_insights> (5.628s)
(✓) Done: Portal dashboard: <new_dashboard> (1.63s)
(✓) Done: Function App: <new_function_app> (39.402s)

    O resultado inclui um link para monitorizar o progresso da implementação no portal Azure.

  8. Após a conclusão do provisionamento, o processo implementa a nova aplicação de funções no portal Azure:

    Deploying services (azd deploy)

(✓) Done: Deploying service function
- Endpoint: https://<new_function_app>.azurewebsites.net/

Configuring EventGrid subscription for API Center

Examples from AI knowledge base

  9. Quando a implementação terminar, confirme que a nova aplicação de função está presente e que a função é publicada.

    Se a apicenter-analyer função não estiver listada ou o Estado não estiver Ativado, publique a função usando as Ferramentas Principais de Funções do Azure.

  10. Configure uma subscrição de evento usando PowerShell ou um bash shell no Visual Studio Code.

Confirmar a função publicada no portal Azure

Quando a implementação estiver concluída, confirme que a nova aplicação de funções está presente no portal Azure e que a função é publicada.

  1. Inicie sessão no portal Azure, navegue até à secção Function App e selecione a sua nova function app na lista.

  2. Na página de Visão Geral da nova aplicação de funções, confirme que o Estado da aplicação de funções está em execução.

  3. Na secção de Funções , confirme que a apicenter-analyer função está listada e que o Estado está Ativado.

    Captura de ecrã da aplicação de funções no portal Azure mostrando o estado Em Execução e a função Ativada.

Publicar a função apicenter-analyzer com as Ferramentas Core do Azure Functions

Se o processo de implementação não publicar a apicenter-analyer função na aplicação de funções no portal Azure, pode executar os seguintes comandos num terminal Visual Studio Code e completar o processo.

  1. Execute o seguinte comando para confirmar que a função não foi publicada na aplicação de funções:

    Nota

    Este comando utiliza o novo grupo de recursos criado pelo processo de implementação da aplicação de funções e não o grupo de recursos do seu centro de API. Substitua <function-app-name> e <new_resource_group_for_function_app> pelo nome da tua aplicação de função e o nome do grupo de recursos da aplicação de funções.

    az functionapp function list --name <function_app_name> --resource-group <new_resource_group_for_function_app> --query "[].name" -o tsv

    A saída do comando deve estar vazia.

  2. No Explorador, expande a src/functions pasta e abre o ApiAnalyzerFunction.ts ficheiro. Esta ação confirma que o ambiente está configurado para procurar conteúdo no local correto.

  3. Confirme que o seu ambiente inclui o gestor de pacotes npm e o ambiente de execução do Node, e instale quaisquer ferramentas conforme necessário:

    node --version
npm --version

  4. Conforme necessário, instale as Ferramentas de Código Azure Functions no ambiente:

    npm install -g azure-functions-core-tools@4 --unsafe-perm true

  5. Execute o seguinte comando para publicar o código da função na aplicação de funções no portal Azure. Substitua <function-app-name> pelo nome do aplicativo de função.

    func azure functionapp publish <function_app_name> --typescript

    O comando mostra a seguinte saída:

    Getting site publishing info...
[2026-02-26T19:58:38.779Z] Starting the function app deployment...
Uploading package...
Uploading 33.8 MB [###############################################################################]
Upload completed successfully.
Deployment completed successfully.
apicenter-analyzer - [eventGridTrigger]

  6. No portal Azure, confirme que a apicenter-analyzer função está agora publicada e ativada para a sua aplicação de funções.

Configurar subscrição de eventos

Depois de a função ser publicada com sucesso na aplicação de funções no portal Azure, pode criar uma subscrição de eventos no seu centro de API para ativar a aplicação de funções quando um ficheiro de definição de API for carregado ou atualizado.

  1. Obtenha o ID do recurso do seu centro de API. Substitua <apic-name> e <resource-group-name> com o nome do seu centro API e o nome do grupo de recursos para o seu centro API.

    #! /bin/bash
apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
    --query "id" --output tsv)

    # PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

  2. Obtenha o ID de recurso da função na aplicação de funções. Neste exemplo, o nome da função é apicenter-analyzer. Substitua <function-app-name> e <resource-group-name> com o nome da tua aplicação de função e o nome do grupo de recursos para a tua aplicação de funções.

    #! /bin/bash
functionID=$(az functionapp function show --name <function-app-name> \
    --function-name apicenter-analyzer --resource-group <resource-group-name> \
    --query "id" --output tsv)

    # PowerShell syntax
$functionID=$(az functionapp function show --name <function-app-name> `
    --function-name apicenter-analyzer --resource-group <resource-group-name> `
    --query "id" --output tsv)

  3. Crie uma subscrição de evento usando o comando az eventgrid event-subscription create. A subscrição criada inclui eventos para adicionar ou atualizar definições de API.

    #! /bin/bash
az eventgrid event-subscription create --name MyEventSubscription \
    --source-resource-id "$apicID" --endpoint "$functionID" \
    --endpoint-type azurefunction --included-event-types \
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

    # PowerShell syntax
az eventgrid event-subscription create --name MyEventSubscription `
    --source-resource-id "$apicID" --endpoint "$functionID" `
    --endpoint-type azurefunction --included-event-types `
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

    A saída do comando mostra detalhes da subscrição de evento. Também pode obter detalhes usando o comando az eventgrid event-subscription show.

    az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"

    Nota

    Pode demorar pouco tempo até a subscrição do evento se propagar para a aplicação funcional.

  4. Navegue até ao seu centro de API no portal Azure e confirme a nova subscrição de evento emSubscrições de Eventos>.

Evento de gatilho no seu centro de API

Para testar a assinatura do evento, tente carregar ou atualizar um arquivo de definição de API associado a uma versão da API no seu centro de API. Por exemplo, carregue um documento OpenAPI ou AsyncAPI. Após a assinatura do evento ser acionada, a aplicação de funções invoca o mecanismo de linting da API para analisar a definição da API.

Para confirmar que a subscrição do evento foi ativada:

  1. Navegue até ao seu centro de API e selecione Eventos.

  2. Selecione a guia de Assinaturas de Evento e selecione a assinatura de evento para a sua aplicação de funções.

  3. Revise as métricas para confirmar que a subscrição do evento foi acionada e o linting foi invocado com sucesso.

    Captura de ecrã das métricas para a subscrição do evento no portal.

    Nota

    Pode levar alguns minutos para que as métricas apareçam.

Após o sistema analisar a definição da API, o motor de linting gera um relatório baseado no guia de estilo da API configurado.

Exibir relatórios de análise de API

Você pode exibir o relatório de análise para sua definição de API no portal do Azure. Depois que uma definição de API é analisada, o relatório lista erros, avisos e informações com base no guia de estilo da API configurada.

No portal, você também pode exibir um resumo dos relatórios de análise para todas as definições de API em seu centro de API.

Relatório de análise para uma definição de API

Para exibir o relatório de análise para uma definição de API em seu centro de API:

  1. No portal, navegue até ao seu centro de API, expanda o Inventário e selecione Ativos.

  2. Na lista de Ativos, selecione a API para a qual adicionou ou atualizou uma definição de API.

  3. Selecione Versões e depois expanda a linha para que a API possa examinar.

  4. Em Definição, selecione o nome da definição que carregou ou atualizou.

  5. Selecione o separador Análise .

    Captura de ecrã do separador Análise para uma definição de API no portal Azure.

O Relatório de Análise de API é aberto e exibe a definição da API e erros, avisos e informações com base no guia de estilo da API configurado. A captura de tela a seguir mostra um exemplo de um relatório de análise de API.

Captura de tela de um relatório de análise de API no portal.

Resumo da análise da API

Pode consultar um resumo dos relatórios de análise para todas as definições de APIs no seu centro de APIs.

  • No portal, navegue até ao seu centro de APIs, expanda Governação e selecione Análise de API.

    Captura de ecrã do resumo da análise da API no portal.

  • O ícone à direita em cada linha abre o Relatório de Análise da API para a definição.

Conteúdos relacionados

  • Last updated on