Partilhar via

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

Este artigo explica como ativar a análise de API no Azure API Center para configurar um motor de análise de código e gatilhos. 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 a Azure Developer CLI (azd) para implementar infraestrutura de linting em uma única etapa, 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 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 aplicação de função e configurar a subscrição do evento.

Nota

Azure API Center também configura automaticamente um motor de linting predefinido e dependências para a análise de APIs. Se habilitar a análise autogerenciada conforme descrito neste artigo, substituirá esses recursos incorporados.

Descrição geral do cenário

Neste cenário, analisa as definições de APIs no seu API center usando o motor de linting Spectral open source. 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 linting da API 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. Configure uma subscrição de eventos num centro de API do Azure que desencadeia 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 guides de estilo API personalizado, 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

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

Os procedimentos seguintes fornecem passos automáticos para que o CLI de Desenvolvedor do Azure (azd) configure a aplicação de função e a subscrição de eventos que permitem verificação e análise no centro de APIs.

Nota

Se preferir configurar o motor e os recursos com implementação manual, consulte o repositório Azure API Center Analyzer GitHub para orientações para implementar a aplicação de funções e configurar a subscrição de eventos.

Executa a amostra usando azd

  1. Clone o repositório de amostras Azure API Center Analyzer 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. No Visual Studio Code Activity Bar, selecione Explorer (Ctrl+Shift+E) para 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 em Visual Studio Code e autentique com a 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 em Azure como <your_user_alias>.

  5. De seguida, inicie sessão no portal do 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 implementar 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 Overview para o seu recurso do centro API na Azure portal.

    • 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, consulte Executar a amostra usando a CLI do 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 Azure portal.

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

    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 termina, confirma que a nova aplicação de função está presente e a função é publicada.

    Se a função apicenter-analyer não estiver listada ou se a Status não estiver Ativada, publicar a função usando as Ferramentas Centrais Azure Functions.

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

Confirmar função publicada no Azure portal

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

  1. Inicie sessão no Azure portal, 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 Azure portal a mostrar o estado Em execução e a função Ativada.

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

Se o processo de implementação não publicar a função apicenter-analyer na aplicação de funções na Azure portal, 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 manager npm e o ambiente de execução node, e instale as ferramentas necessárias:

    node --version
npm --version

  4. Conforme necessário, instale as Azure Functions Code Tools 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 Azure portal. 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 Azure portal, confirma que a função apicenter-analyzer está agora publicada e ativada para a tua 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 Azure portal, 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 API no Azure portal e confirme a nova subscrição do evento em Eventos>Subscriçõ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

Pode consultar o relatório de análise para a definição da sua API no Azure portal. 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 na Azure portal.

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