Habilitar a análise de API no centro de API – autogerenciada

Este artigo explica como habilitar a análise de API no Centro de API do Azure configurando manualmente um mecanismo de lint e gatilhos. Esses recursos analisam suas definições de API para aderir às regras de estilo organizacional, gerando relatórios individuais e resumidos. A análise da API ajuda a identificar e corrigir erros comuns e inconsistências nas suas definições de API.

Observação

Na versão prévia, o Centro de API do Azure configura automaticamente um mecanismo de lint padrão e dependências para a análise da API. Se você habilitar a análise autogerenciada conforme descrito neste artigo, substitua esses recursos internos.

Visão geral do cenário

Nesse cenário, você vai analisar as definições de API no seu centro de API usando o mecanismo de lint de código aberto Espectral. Um aplicativo do Azure Functions executa o mecanismo de lint 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 APIs personalizável. Gera-se um relatório de análise que você pode ver no centro de API.

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

1. Implantar um aplicativo do Azure Functions que executa o mecanismo de lint Spectral em uma definição de API.

2. Configurar uma assinatura de evento em um centro de API do Azure para disparar o aplicativo de funções.

3. Um evento é disparado quando uma definição de API é adicionada ou substituída no centro de API.

4. Ao receber o evento, o aplicativo de funções invoca o mecanismo de lint Spectral.

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

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

Opções para implantar o mecanismo de lint e a assinatura de evento

Este artigo apresenta duas opções para implantar o mecanismo de lint e a assinatura de evento no centro de API:

• Implantação automatizada – Use o Azure Developer CLI (azd) para implantação em uma etapa da infraestrutura de lint. Essa opção é recomendada para um processo de implantação simplificado.

• Implantação manual – Siga as diretrizes passo a passo para implantar o aplicativo do Azure Functions e configurar a assinatura de evento. Essa opção é recomendada se você prefere implantar e gerenciar os recursos manualmente.

Limitações

• Atualmente, o lint dá suporte apenas a arquivos de especificação JSON ou YAML, como documentos de especificação do OpenAPI ou da AsyncAPI.
• Por padrão, o mecanismo de lint usa o conjunto de regras spectral:oas integrado. Para ampliar o conjunto de regras ou criar guias de estilo de APIs personalizados, confira o repositório do Spectral no GitHub.
• O aplicativo de funções do Azure que invoca o lint é cobrado separadamente e você precisa mantê-lo e gerenciá-lo.

Pré-requisitos

• Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.

• O provedor de recursos da Grade de Eventos registrado na sua assinatura. Se precisar registrar o provedor de recursos da Grade de Eventos, confira Fazer uma assinatura de eventos publicados por um parceiro com a Grade de Eventos do Azure.

• Para a CLI do Azure:

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

    

  • Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

    • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

  Observação

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

  Confira as notas sobre a versão para ver as últimas alterações e atualizações no apic-extension.

  Observação

  Os exemplos de comando da CLI do Azure incluídos neste artigo podem ser executados no PowerShell ou em um shell do Bash. Sempre que necessário, devido às diferentes sintaxes variáveis, são fornecidos exemplos de comando separados para os dois shells.

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

Esta seção apresenta etapas automatizadas que usam o Azure Developer CLI para configurar o aplicativo do Azure Functions e a assinatura de evento que permitem o lint e a análise no centro de API. Você também pode configurar os recursos manualmente.

Outros pré-requisitos para essa opção

• Azure Developer CLI (azd)

Execute a amostra usando azd

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

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

3. Na pasta resources/rulesets você poderá encontrar um arquivo oas.yaml. Esse arquivo reflete seu guia de estilo de APIs atual e pode ser modificado com base nas necessidades e requisitos da sua organização.

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

   azd auth login
   
   az login
   

5. Execute o comando a seguir para implantar a infraestrutura de lint na sua assinatura do Azure.

   azd up
   

6. Siga os prompts para fornecer as informações e as configurações de implantação necessárias, como o nome do ambiente e o nome do centro de API. Para obter detalhes, confira Como executar a amostra usando o Azure Developer CLI (azd).

   Observação

   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 Eventos>Assinaturas de evento para ver a assinatura de evento que foi criada.

Agora você pode carregar um arquivo de definição de API no centro de API para disparar a assinatura de evento e executar o mecanismo de lint.

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

Esta seção fornece as etapas manuais de implantação para configurar o aplicativo do Azure Functions e a assinatura de evento, a fim de habilitar o lint e a análise no centro de API. Use também o Azure Developer CLI para implantação automatizada.

Outros pré-requisitos para essa opção

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

Etapa 1. Implantar seu aplicativo do Azure Functions

Para implantar o aplicativo do Azure Functions que executa a função de lint nas definições de API:

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

2. Na pasta resources/rulesets você poderá encontrar um arquivo oas.yaml. Esse arquivo reflete seu guia de estilo de APIs atual e pode ser modificado com base nas necessidades e requisitos da sua organização.

3. Opcionalmente, execute o aplicativo de funções localmente para testá-lo. Para obter detalhes, confira o arquivo README no repositório.

4. Implantar o aplicativo de funções no Azure. Para obter as etapas, confira Início Rápido: Criar uma função no Azure com TypeScript usando o Visual Studio Code.

   Observação

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

5. Entre no portal do Azure e acesse o aplicativo de funções.

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

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

   

Etapa 2. Configurar a identidade gerenciada no seu aplicativo de funções

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

Portal

1. No portal do Azure, navegue até seu aplicativo de funções e selecione Identidade na seção Configurações.
2. Na guia Atribuída pelo sistema, configure o Status como Ativa e selecione Salvar.

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

1. No portal do Azure, navegue até seu centro de API e selecione Controle de acesso (IAM).
2. Selecione + Adicionar > Adicionar atribuição de função.
3. Selecione funções de Função de trabalho e selecione Gerenciador de Conformidade do Centro de API do Azure. Selecione Avançar.
4. Na página Membros, em Atribuir acesso a selecione Identidade Gerenciada > + Selecionar membros.
5. Na página Selecionar identidades gerenciadas, pesquise e selecione a identidade gerenciada do aplicativo de funções. Clique em Selecionar e em Avançar.
6. Examine a atribuição de função e selecione Examinar + atribuir.

CLI do Azure

1. Habilite a identidade atribuída pelo sistema do aplicativo de funções usando o comando az functionapp identity assign. Substitua <function-app-name> e <resource-group-name> pelo nome do seu aplicativo de funções e pelo nome do grupo de recursos. O comando a seguir armazena a ID de entidade de segurança da identidade gerenciada atribuída pelo sistema na variável principalID.

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. Obtenha a ID do recurso no seu centro de API. Substitua <apic-name> e <resource-group-name> pelo nome do seu centro de API e pelo nome do grupo de recursos.

   #! /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)
   

3. Atribua a identidade gerenciada do aplicativo de funções a função do Gerenciador de Conformidade da Central de API do Azure no centro de API usando o comando az role assignment create.

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

Etapa 3. Configurar a assinatura de evento no seu centro de API

Agora, crie uma assinatura de evento no centro de API para disparar o aplicativo de funções 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.

Portal

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 do evento, faça o seguinte:

   1. Insira um Nome descritivo para a assinatura do evento e selecione Esquema da Grade de Eventos.

   2. Nos Detalhes do tópico, insira um Nome de tópico do sistema de sua escolha.

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

      • Definição de API adicionada
      • Definição de API atualizada

   4. Em Detalhes do ponto de extremidade, selecione Azure Functions > Configure um ponto de extremidade.

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

   6. Selecione Criar.

      

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

   

CLI do Azure

1. Obtenha a ID do recurso no seu centro de API. Substitua <apic-name> e <resource-group-name> pelo nome do seu centro de API e pelo nome do grupo de recursos.

   #! /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 a ID do recurso da função no aplicativo de funções. Nesse exemplo, o nome da função é apicenter-analyzer. Substitua <function-app-name> e <resource-group-name> pelo nome do seu aplicativo de funções e pelo nome do grupo de recursos.

   #! /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 assinatura de evento usando o comando az eventgrid event-subscription create. A assinatura que é 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 os detalhes da assinatura do evento. Você também pode obter detalhes usando o comando az eventgrid event-subscription show. Por exemplo:

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

Observação

Pode levar algum tempo para a assinatura do evento se propagar para o aplicativo de funções.

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 de API no seu centro de API. Por exemplo, carregue um documento do OpenAPI ou da AsyncAPI. Após a assinatura do evento ser disparada, o aplicativo de funções invoca o mecanismo de lint de APIs para analisar a definição da API.

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

Para confirmar se a assinatura do evento foi disparada:

1. Navegue até seu centro de API e selecione Eventos no menu do lado esquerdo.

2. Selecione a guia Assinaturas de Eventos e selecione a assinatura do evento para o seu aplicativo de funções.

3. Revise as métricas para confirmar se a assinatura do evento foi disparada e se o lint foi invocado com sucesso.

   

   Observação

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

Após analisar a definição da API, o mecanismo de lint gera um relatório com base no guia de estilo de APIs 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 de API configurado.

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 de uma definição de API no centro de API:

1. No portal, navegue até a versão da API no centro de API em que você adicionou ou atualizou uma definição de API.
2. No menu à esquerda, em Detalhes, selecione Definições.
3. Escolha a definição de API que você carregou ou atualizou.
4. Selecione a guia Análise.

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

Resumo da análise de API

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

1. No portal, navegue até seu centro de API.

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

   

Conteúdo relacionado

Saiba mais sobre a Grade de Eventos:

• Habilitar a análise de API no centro de API – Gerenciada pela Microsoft
• Tópicos do sistema na Grade de Eventos do Azure
• Entrega da Grade de Eventos por push: conceitos
• Esquema da Grade de Eventos para o Centro de API do Azure