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

Este artigo explica como habilitar a análise de API na Central de APIs do Azure configurando manualmente um mecanismo de revestimento e gatilhos. A análise de API oferece recursos de revestimento para analisar definições de API no centro de API da sua organização. O Linting garante que suas definições de API sigam as regras de estilo organizacional, gerando relatórios individuais e resumidos. Use a análise de API para identificar e corrigir erros e inconsistências comuns em suas definições de API.

Descrição geral do cenário

Nesse cenário, você analisa as definições de API em seu centro de API usando o mecanismo de revestimento de código aberto Spectral . Um aplicativo do Azure Functions executa o mecanismo de revestimento em resposta a eventos em sua central de APIs. 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 revestimento e a análise em seu centro de API.

1. Implante um aplicativo do Azure Functions que execute o mecanismo de revestimento espectral em uma definição de API.

2. Configure uma assinatura de evento em uma central de API do Azure para acionar o aplicativo de função.

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, o aplicativo de função invoca o mecanismo de revestimento espectral.

5. O mecanismo de revestimento verifica se as APIs definidas na definição estão em conformidade com o guia de estilo da API da organização e gera um relatório.

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

Opções para implantar o mecanismo de revestimento e a assinatura de eventos

Este artigo fornece duas opções para implantar o mecanismo de revestimento e a assinatura de eventos em sua central de APIs:

• Implantação automatizada - Use a CLI do desenvolvedor do Azure (azd) para implantação em uma etapa da infraestrutura de alinhamento. Essa opção é recomendada para um processo de implantação simplificado.

• Implantação manual - Siga as orientações passo a passo para implantar o aplicativo Azure Functions e configurar a assinatura do evento. Essa opção é recomendada se você preferir implantar e gerenciar os recursos manualmente.

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, o mecanismo de revestimento usa o conjunto de spectral:oas regras interno. Para estender o conjunto de regras ou criar guias de estilo de API personalizados, consulte o repositório Spectral GitHub.
• O aplicativo de função do Azure que invoca linting é cobrado separadamente e você o gerencia e mantém.

Pré-requisitos

• 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.

• O provedor de recursos da Grade de Eventos registrado em sua assinatura. 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.

• Para a CLI do Azure:

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

    

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

  Nota

  az apic comandos exigem a extensão da CLI do apic-extension Azure. Se você não tiver usado az apic comandos, a extensão pode ser instalada dinamicamente quando você executa seu primeiro az apic comando, ou você pode instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.

  Consulte as notas de versão para obter as alterações e atualizações mais recentes no apic-extension.

  Nota

  Os exemplos de comandos da CLI do Azure neste artigo podem ser executados no PowerShell ou em um shell bash. Quando necessário devido à sintaxe variável diferente, exemplos de comandos separados são fornecidos para os dois shells.

azd implantação do aplicativo Azure Functions e assinatura de evento

Esta seção fornece etapas automatizadas usando a CLI do Desenvolvedor do Azure para configurar o aplicativo Azure Functions e a assinatura de eventos que habilitam o linting e a análise em sua central de API. Você também pode configurar os recursos manualmente.

Outros pré-requisitos para esta opção

• Azure Developer CLI (azd)

Execute o exemplo usando azd

1. Clone o repositório GitHub e abra-o no Visual Studio Code.

2. Altere o diretório para a APICenter-Analyzer pasta no repositório.

3. resources/rulesets Na pasta, você pode encontrar um oas.yaml arquivo. Esse arquivo reflete seu guia de estilo de API atual e pode ser modificado com base em suas necessidades e requisitos organizacionais.

4. Autentique-se com a CLI do Desenvolvedor do Azure e a CLI do Azure usando os seguintes comandos:

   azd auth login
   
   az login
   

5. Execute o seguinte comando para implantar a infraestrutura de revestimento em sua assinatura do Azure.

   azd up
   

6. Siga as instruções para fornecer as informações e configurações de implantação necessárias, como o nome do ambiente e o nome do centro de API. Para obter detalhes, consulte Executando o exemplo usando a CLI do Desenvolvedor do Azure (azd).

   Nota

   A implantação pode levar alguns minutos.

7. Após a conclusão da implantação, navegue até o centro de API no portal do Azure. No menu à esquerda, selecione Assinaturas>de eventos para exibir a assinatura de evento que foi criada.

Agora você pode carregar um arquivo de definição de API para o seu centro de API para acionar a assinatura de evento e executar o mecanismo de alinhamento.

Etapas manuais para configurar o aplicativo Azure Functions e a assinatura de eventos

Esta seção fornece as etapas manuais de implantação para configurar o aplicativo Azure Functions e a assinatura de eventos para habilitar o linting e a análise em sua central de APIs. Você também pode usar a CLI do Desenvolvedor do Azure para implantação automatizada.

Outros pré-requisitos para esta opção

• Código do Visual Studio com a extensão do Azure Functions v1.10.4 ou posterior.

Passo 1. Implantar seu aplicativo Azure Functions

Para implantar o aplicativo Azure Functions que executa a função linting em definições de API:

1. Clone o repositório GitHub e abra-o no Visual Studio Code.

2. resources/rulesets Na pasta, você pode encontrar um oas.yaml arquivo. Esse arquivo reflete seu guia de estilo de API atual e pode ser modificado com base em suas necessidades e requisitos organizacionais.

3. Opcionalmente, execute o aplicativo de função localmente para testá-lo. Para obter detalhes, consulte o arquivo LEIA-ME no repositório.

4. Implante o aplicativo de função no Azure. Para conhecer as etapas, consulte Guia de início rápido: criar uma função no Azure com TypeScript usando o Visual Studio Code.

   Nota

   A implantação do aplicativo de função pode levar alguns minutos.

5. Entre no portal do Azure e vá para o aplicativo de função.

6. Na página Visão geral, verifique os seguintes detalhes:

   • Confirme se o Status do aplicativo de função está em execução.
   • Em Funções, confirme se o Status da função apicenter-analyzer está Habilitado.

   

Passo 2. Configurar a identidade gerenciada em seu aplicativo de função

Para permitir que o aplicativo de função acesse o centro de API, configure uma identidade gerenciada para o aplicativo de função. As etapas a seguir mostram como habilitar e configurar uma identidade gerenciada atribuída pelo sistema para o aplicativo de função usando o portal do Azure ou a CLI do Azure.

Passo 3. Configurar a subscrição de eventos no seu centro de API

Agora, crie uma assinatura de evento em sua central de API para acionar o aplicativo de função quando um arquivo de definição de API for carregado ou atualizado. As etapas a seguir mostram como criar a assinatura de evento usando o portal do Azure ou a CLI do Azure.

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. Depois que a assinatura do evento é acionada, o aplicativo de função invoca o mecanismo de revestimento da API para analisar a definição da API.

• Para obter etapas detalhadas para adicionar uma API, versão e definição de API ao seu centro de APIs, consulte Tutorial: Registrar APIs em seu centro de APIs.
• Para criar uma API carregando um arquivo de definição de API usando a CLI do Azure, consulte Registrar API de um arquivo de especificação.

Para confirmar que a assinatura do evento foi acionada:

1. Navegue até a central de APIs e selecione Eventos no menu à esquerda.

2. Selecione a guia Assinaturas de evento e selecione a assinatura de evento para seu aplicativo de função.

3. Revise as métricas para confirmar se a assinatura do evento foi acionada e se o linting foi invocado com êxito.

   

   Nota

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

Depois de analisar a definição da API, o mecanismo de revestimento gera um relatório com base 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é a versão da API no seu centro de API onde você adicionou ou atualizou uma definição de API.
2. No menu à esquerda, em Detalhes, selecione Definições.
3. Selecione a definição de API que você carregou ou atualizou.
4. Selecione a guia Análise .

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.

Resumo da análise da API

Para exibir um resumo dos relatórios de análise para todas as definições de API em seu centro de API:

1. No portal, navegue até o centro de APIs.

2. No menu à esquerda, em Governança, selecione Análise de API. O resumo é exibido.

   

Conteúdos relacionados

Saiba mais sobre a Grelha de Eventos:

• Habilite a análise de API em seu centro de API - gerenciado pela Microsoft
• Tópicos do sistema na Grade de Eventos do Azure
• Entrega por push da grade de eventos - conceitos
• Esquema de Grade de Eventos para a Central de APIs do Azure