Habilite o linting e a análise para governança de API em seu centro de API

Este artigo mostra como habilitar o linting para analisar definições de API no centro de API da sua organização para conformidade com as regras de estilo de API da sua organização. O Linting gera um relatório de análise que você pode acessar em seu centro de API. Use o revestimento e a análise de API para detetar 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 conformidade com a API 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 será instalada dinamicamente quando você executar o primeiro az apic comando. Saiba mais sobre as extensões da CLI do Azure.

  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.

Portal

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.

CLI do Azure

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

   #! /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 o ID do recurso do seu centro de API. Substitua e <resource-group-name> pelo nome do centro de <apic-name> API e pelo nome do grupo de recursos.

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

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

3. Atribua a identidade gerenciada do aplicativo de função à função Gerenciador de Conformidade do Centro 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 
   

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.

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

      

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

   

CLI do Azure

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

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

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

2. Obtenha o ID de recurso da função no aplicativo de função. Neste exemplo, o nome da função é apicenter-analyzer. Substitua <function-app-name> e <resource-group-name> com o nome do aplicativo de função e o 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 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 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"
   

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

• 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