Análisis de las API en el Centro de API: Administrado por Microsoft

El Centro de API de su organización incluye capacidades de análisis de datos integradas administradas por Microsoft (vista previa) para analizar las definiciones de API y verificar su cumplimiento con las reglas de estilo organizacional, generando informes individuales y resumidos. El análisis de API identifica y ayuda a corregir errores e incoherencias comunes en las definiciones de API.

Con el análisis de API:

  • El Centro de API de Azure analiza automáticamente las definiciones de API siempre que agregue o actualice una definición de API. El linting de las definiciones de API se realiza de forma predeterminada con un spectral:oas conjunto de reglas (guía de estilo API).
  • Los informes de análisis de API se generan en Azure Portal, en el que se muestra cómo las definiciones de API se ajustan a la guía de estilo.
  • Use perfiles de análisis para especificar el conjunto de reglas y las condiciones de filtro para las API que se analizan. Personalice el conjunto de reglas de un perfil mediante la extensión del Centro de API de Azure para Visual Studio Code.

Importante

Si lo prefiere, puede habilitar el análisis y el control de linting autoadministrados mediante una función de Azure personalizada, anulando las capacidades integradas. Deshabilitar cualquier función que se use para la linting autoadministrada antes de usar el análisis de API administrada.

Limitaciones

  • Actualmente, solo se analizan los documentos de especificación OpenAPI y AsyncAPI en formato JSON o YAML.
  • Hay límites para el número de perfiles de análisis y el número máximo de definiciones de API analizadas. El análisis puede tardar entre unos minutos hasta 24 horas en completarse.

Requisitos previos

Visualización de informes de análisis de API

Puede ver un resumen del análisis y los informes del análisis de las definiciones de API en Azure Portal. Después de analizar las definiciones de API, el informe enumera los errores, las advertencias y la información en función de la guía de estilo de API configurada.

En el informe de análisis de API, revise también el conjunto de reglas que se usó para el análisis y el historial de pasos de linting.

Para ver un resumen del análisis en API Center:

  1. En el portal, vaya al centro de API.

  2. En el menú de la izquierda, en Gobernanza, seleccione Análisis de API. Aparece el resumen.

    Captura de pantalla del resumen del análisis de API en el portal.

  3. Opcionalmente, seleccione el icono del informe de análisis de API para una definición de API. Aparece el informe de análisis de API de la definición, como se muestra en el recorte de pantalla siguiente.

    Captura de pantalla de un informe de análisis de API en el portal.

    Sugerencia

    También puede ver el informe de análisis de API seleccionando Análisis en la barra de menús de la definición de API.

Administrar perfiles de análisis

Azure API Center usa perfiles de análisis para el linting y el análisis de las API. Un perfil de análisis especifica un conjunto de reglas y, opcionalmente, las condiciones de filtro para las API que se analizan. El perfil de análisis predeterminado aplica el spectral:oas conjunto de reglas a todas las definiciones de OpenAPI y AsyncAPI.

Puede personalizar el conjunto de reglas y definir condiciones de filtro en el perfil predeterminado, o bien puede crear un perfil nuevo. Por ejemplo, es posible que quiera usar un perfil para las API que están en desarrollo y otra para las API que están en producción.

Nota:

En el plan Estándar del Centro de API, puede crear hasta tres perfiles de análisis. Solo se admite un único perfil en el plan Gratis.

Para crear un perfil de análisis:

  1. En Azure Portal, vaya al Centro de API.
  2. En el menú de la izquierda, en Gobernanza, seleccione API Analysis>Manage analysis profiles> perfiles de análisis de API+ Crear perfil de análisis).
  3. En el panel Crear nuevo perfil de análisis , escriba un nombre y una descripción para el perfil.
  4. En Ruleset, aparece el tipo de analizador (herramienta de análisis) para el conjunto de reglas. Actualmente solo se admite Spectral.
  5. En Definir condiciones de filtro, agregue una o varias condiciones de filtro para las definiciones de API a las que se aplica el perfil.
  6. Seleccione Crear.

Captura de pantalla de la creación de un perfil de análisis en el portal.

El perfil se crea y se genera un esqueleto del conjunto de reglas. Para ver el conjunto de reglas actual, seleccione el perfil y, en el menú contextual (...), seleccione Ver el conjunto de reglas.

Para personalizar el conjunto de reglas, continúe con las secciones siguientes.

Personalización del conjunto de reglas del perfil

Use la extensión Visual Studio Code para Azure API Center para personalizar el conjunto de reglas de un perfil. Después de personalizar el conjunto de reglas y probarlo localmente, puede volver a implementarlo en el centro de API.

  1. En Visual Studio Code, seleccione el icono de Azure API Center en la barra de actividades.
  2. En el panel Centro de API, expanda el recurso del Centro de API con el que trabaja y expanda Perfiles.
  3. Expanda el perfil que desea modificar y seleccione ruleset.yaml.
  4. Modifique o reemplace el contenido según sea necesario.
  5. Guarde los cambios en ruleset.yaml.

Prueba local del conjunto de reglas

Antes de implementar el conjunto de reglas personalizado en la instancia de API Center, valídelo de forma local. La extensión de Azure API Center para Visual Studio Code proporciona compatibilidad integrada con el linting de especificaciones de API con Spectral.

  1. En Visual Studio Code, utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos.

  2. Escriba Azure API Center: Establecer guía de estilo de API activa y pulse Intro.

  3. Elija Seleccionar archivo local y especifique el archivo ruleset.yaml que ha personalizado. Presione Intro.

    Este paso convierte el conjunto de reglas personalizado en la guía de estilo de API activa para linting local.

Ahora, al abrir un archivo de definición de API basado en OpenAPI, se desencadena automáticamente una operación de linting local en Visual Studio Code. Los resultados se muestran en línea en el editor y en la ventana Problemas (Ver > Problemas o Ctrl+Shift+M).

Sugerencia

Los desarrolladores de API de su organización también pueden usar esta funcionalidad de linting local para ayudar a mejorar sus definiciones de API antes de registrar las API en el centro de API.

Captura de pantalla del proceso de linting de una definición de API en Visual Studio Code.

Revise los resultados del linting. Realice los ajustes necesarios en el conjunto de reglas y continúe probándolo localmente hasta que funcione como desee.

Desplegar el conjunto de reglas a su centro de API

Para implementar el conjunto de reglas personalizado en la instancia de API Center:

  1. En Visual Studio Code, seleccione el icono de Azure API Center en la barra de actividades.
  2. En el panel de API Center, expanda el recurso de API Center en el que ha personalizado el conjunto de reglas.
  3. Expandir Perfiles.
  4. Haga clic con el botón derecho en el perfil en el que ha personalizado el conjunto de reglas y seleccione Implementar reglas en el Centro de API.

Un mensaje le notificará una vez que las reglas se hayan implementado correctamente en la instancia de API Center. El motor de linting usa el conjunto de reglas actualizado para analizar las definiciones de API en el perfil.

Para ver los resultados del linting con el conjunto de reglas actualizado, consulte los informes de análisis de API en el portal.

Contenido relacionado

  • Last updated on