Analise APIs em seu centro de APIs - gerenciado pela Microsoft

O centro de API da sua organização inclui recursos de linting internos geridos pela Microsoft (pré-visualização) para analisar definições de API quanto à conformidade com as 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. O linting para as definições da tua API é feito por defeito com um spectral:oas conjunto de regras (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.
  • Use perfis de análise para especificar o conjunto de regras e as condições de filtro para as APIs analisadas. Personalize o conjunto de regras de um perfil usando a extensão Azure API Center para Visual Studio Code.

Importante

Se preferir, pode habilitar o linteamento e a análise autogerenciados usando uma função personalizada do Azure, de forma a substituir as capacidades integradas. Desative qualquer função usada para verificação de código gerenciada pelo utilizador antes de usar a análise de API automática.

Limitações

  • Atualmente, apenas documentos de especificação OpenAPI e AsyncAPI em formato JSON ou YAML são analisados.
  • Existem limites para o número de perfis de análise e para o número máximo de definições de APIs 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 lintagem.

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.

Gerir perfis de análise

Azure API Center utiliza perfis de análise para linting e análise de APIs. Um perfil de análise especifica um conjunto de regras e, opcionalmente, filtra condições para APIs que são analisadas. O perfil de análise padrão aplica o ruleset spectral:oas a todas as definições OpenAPI e AsyncAPI.

Pode personalizar o conjunto de regras e definir condições de filtro no perfil padrão, ou pode criar um novo perfil. Por exemplo, pode querer usar um perfil para APIs em desenvolvimento e outro diferente para APIs em produção.

Observação

No plano Standard do API Center, pode criar até três perfis de análise. Apenas um único perfil é suportado no plano Gratuito.

Para criar um perfil de análise:

  1. No portal do Azure, navegue até o centro de APIs.
  2. No menu à esquerda, em Governança, selecione Análise de API>Gerir perfis de análise>+ Criar perfil de análise.
  3. No painel Criar novo perfil de análise , insira um Nome e uma Descrição para o perfil.
  4. No Ruleset, o tipo de analisador (motor de linting) para o ruleset é exibido. Atualmente, só o Spectral é suportado.
  5. Em Definir condições de filtro, adicione uma ou mais condições de filtro para definições de API a que o perfil é aplicado.
  6. Selecione Criar.

Captura de ecrã da criação de um perfil de análise no portal.

O perfil é criado e uma estrutura de regras é criada. Para visualizar o conjunto de regras atual, selecione o perfil e, no menu de contexto, selecione Visualizar o conjunto de regras.

Para personalizar o conjunto de regras, continue para as secções seguintes.

Personalize o conjunto de regras do perfil

Use a extensão Visual Studio Code para o Azure API Center para personalizar o conjunto de regras de um perfil. Depois de personalizar o conjunto de regras e testá-lo localmente, podes implementá-lo de volta no teu centro de API.

  1. No Visual Studio Code, selecione o ícone da Central de API do Azure na Barra de atividades.
  2. No painel do API Center, expanda o recurso do API center com que está a trabalhar e expanda Perfis.
  3. Expanda o perfil que pretende modificar e selecione ruleset.yaml.
  4. Modifique ou substitua o conteúdo conforme necessário.
  5. Salve suas alterações em ruleset.yaml.

Testar conjunto de regras localmente

Antes de implantar o conjunto de regras personalizado em seu centro de APIs, valide-o localmente. A extensão do Centro de APIs do Azure para Visual Studio Code oferece suporte integrado para verificação de especificação de APIs 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: Definir o Guia de Estilo de API ativo e pressione Enter.

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

    Este passo torna o conjunto de regras personalizado o guia de estilo ativo da API para o linting local.

Agora, ao abrir um arquivo de definição de API baseado em OpenAPI, uma operação de linting 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 na sua organização também podem usar esse recurso de análise estática local para ajudar a melhorar as suas definições de API antes de registrar APIs no centro de API da sua organização.

Captura de ecrã de verificação 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. Expandir Perfis.
  4. Clique com o botão direito no perfil onde personalizou o conjunto de regras e selecione Implementar Regras no Centro de API.

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

Para ver os resultados do linting com as regras atualizadas, consulte os relatórios de análise de API no portal.

Conteúdos relacionados

  • Last updated on