Partilhar via

Analise APIs em seu centro de APIs - gerenciado pela Microsoft

  • Artigo

O centro de API da sua organização inclui recursos internos de forro gerenciados pela Microsoft (visualização) para analisar definições de API para aderência às regras de estilo organizacional, gerando relatórios individuais e resumidos. A análise de API identifica e ajuda a corrigir erros e inconsistências comuns em suas definições de API.

Com análise API:

  • A Central de API do Azure analisa automaticamente suas definições de API sempre que você adiciona ou atualiza uma definição de API. As definições de API são alinhadas por padrão com um conjunto de regras spectral:oas (guia de estilo da API).
  • Os relatórios de análise de API são gerados no portal do Azure, mostrando como suas definições de API estão em conformidade com o guia de estilo.
  • Você pode usar a extensão do Centro de API do Azure para Visual Studio Code para personalizar e testar seu próprio guia de estilo de API localmente e, em seguida, implantá-lo em seu centro de API.

Importante

Se preferir, você pode habilitar o forro e a análise autogerenciados usando uma função personalizada do Azure, substituindo os recursos internos. Desative qualquer função usada para forro autogerenciado antes de usar a análise de API gerenciada.

Limitações

  • Atualmente, apenas documentos de especificação OpenAPI e AsyncAPI em formato JSON ou YAML são analisados.
  • Atualmente, você configura um único conjunto de regras e ele é aplicado a todas as definições de OpenAPI em seu centro de API.
  • Há limites para o número máximo de definições de API analisadas. A análise pode levar de alguns minutos a até 24 horas para ser concluída.

Pré-requisitos

Exibir relatórios de análise de API

Exiba um resumo de análise e os relatórios de análise para suas definições de API no portal do Azure. Depois que as definições de API são analisadas, os relatórios listam erros, avisos e informações com base no guia de estilo da API configurado.

No relatório de análise da API, revise também o conjunto de regras que foi usado para a análise e o histórico de passes de forro.

Para visualizar um resumo de análise no 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.

  3. Opcionalmente, selecione o ícone Relatório de análise de API para uma definição de API. O relatório de análise de API da definição é exibido, conforme mostrado na captura de tela a seguir.

    Captura de tela de um relatório de análise de API no portal.

    Gorjeta

    Você também pode exibir o relatório de análise da API selecionando Análise na barra de menus da definição da API.

Personalizar conjunto de regras

Você pode usar a extensão do Centro de API do Azure para Visual Studio Code para personalizar o conjunto de regras padrão para seu centro de API ou substituí-lo como o guia de estilo da API da sua organização. Por exemplo, você pode estender o conjunto de regras ou adicionar funções personalizadas.

Para personalizar ou substituir o conjunto de regras:

  1. No Visual Studio Code, selecione o ícone da Central de API do Azure na Barra de atividades.
  2. Abra a .api-center-rules pasta na raiz da sua pasta de trabalho.
  3. Na pasta do recurso do centro de APIs, abra o ruleset.yml arquivo.
  4. Modifique ou substitua o conteúdo conforme necessário.
  5. Salve suas alterações em ruleset.yml.

Conjunto de regras de teste localmente

Antes de implantar o conjunto de regras personalizado em seu centro de APIs, valide-o localmente. A extensão do Centro de API do Azure para Visual Studio Code fornece suporte integrado para forro de especificação de API com Spectral.

  1. No Visual Studio Code, use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos.

  2. Digite Central de API do Azure: defina o Guia de Estilo da API ativa e pressione Enter.

  3. Escolha Selecionar arquivo local e especifique o ruleset.yml arquivo que você personalizou. Pressione Enter.

    Esta etapa torna o conjunto de regras personalizado o guia de estilo da API ativa para forro.

Agora, quando você abre um arquivo de definição de API baseado em OpenAPI, uma operação de revestimento local é acionada automaticamente no Visual Studio Code. Os resultados são exibidos em linha no editor e na janela Problemas (Ver > Problemas ou Ctrl+Shift+M).

Gorjeta

Os desenvolvedores de API em sua organização também podem usar esse recurso de revestimento local para ajudar a melhorar suas definições de API antes de registrar APIs em seu centro de APIs.

Captura de tela de forro de uma definição de API no Visual Studio Code.

Analise os resultados do forro. Faça os ajustes necessários no conjunto de regras e continue a testá-lo localmente até que ele seja executado da maneira desejada.

Implantar o conjunto de regras no seu centro de API

Para implantar o conjunto de regras personalizado em seu centro de API:

  1. No Visual Studio Code, selecione o ícone da Central de API do Azure na Barra de atividades.
  2. No painel Centro de API, expanda o recurso do Centro de API no qual você personalizou o conjunto de regras.
  3. Clique com o botão direito do mouse em Regras e selecione Implantar regras na Central de APIs.

Uma mensagem notifica você depois que as regras são implantadas com êxito no seu centro de API. O mecanismo de revestimento usa o conjunto de regras atualizado para analisar definições de API.

Para ver os resultados do alinhamento com o conjunto de regras atualizado, exiba os relatórios de análise de API no portal.

Conteúdos relacionados