Partilhar via


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

Nota

Na visualização, a Central de API do Azure configura automaticamente um mecanismo de revestimento padrão e dependências para análise de API. Se você habilitar a análise autogerenciada conforme descrito neste artigo, substituirá esses recursos internos.

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.

Diagrama mostrando como o revestimento da API funciona na Central de APIs do Azure.

  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

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

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.

    Captura de ecrã da aplicação funcional no portal.

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.

  1. No portal do Azure, navegue até seu aplicativo de função e selecione Identidade na seção Configurações.
  2. Na guia Sistema atribuído, defina o Status como Ativado e selecione Salvar.

Agora que a identidade gerenciada está habilitada, atribua-lhe a função Gerenciador de Conformidade do Centro de API do Azure para acessar a Central de APIs.

  1. No portal do Azure, navegue até o centro de API e selecione Controle de acesso (IAM).
  2. Selecione + Adicionar > atribuição de função.
  3. Selecione Funções de função de trabalho e, em seguida, selecione Azure API Center Compliance Manager. Selecione Seguinte.
  4. Na página Membros, em Atribuir acesso a, selecione Identidade > gerenciada + Selecionar membros.
  5. Na página Selecionar identidades gerenciadas, procure e selecione a identidade gerenciada do aplicativo de função. Clique em Selecionar e, em seguida, em Avançar.
  6. Reveja a atribuição de função e selecione Rever + atribuir.

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.

  1. No portal do Azure, navegue até o centro de API e selecione Eventos.

  2. Na guia Introdução, selecione Função do Azure.

  3. Na página Criar Assinatura de Evento, faça o seguinte:

    1. Insira um Nome descritivo para a assinatura do evento e selecione Esquema de grade de eventos.

    2. Em Detalhes do tópico, insira um nome de tópico do sistema de sua escolha.

    3. Em Tipos de Evento, selecione os seguintes eventos:

      • Definição de API adicionada
      • Definição de API atualizada
    4. Em Detalhes do Ponto de Extremidade, selecione Função > do Azure Configurar um ponto de extremidade.

    5. Na página Selecionar Função do Azure, selecione o aplicativo de função e a função apicenter-linter que você configurou. Clique em Confirmar seleção.

    6. Selecione Criar.

      Captura de ecrã da criação da subscrição do evento no portal.

  4. Selecione a guia Assinaturas de eventos e selecione Atualizar. Confirme se o estado de provisionamento da assinatura do evento é Bem-sucedido.

    Captura de ecrã do estado da subscrição do evento no portal.

Nota

Pode levar um curto período de tempo para que a assinatura do evento se propague para o aplicativo de função.

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

    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.

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 . Captura de tela da guia Análise para definição de API no 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

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.

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

Saiba mais sobre a Grelha de Eventos: