Habilitación de linting y análisis para la gobernanza de API en el centro de API

En este artículo se muestra cómo habilitar la linting para analizar las definiciones de API en el Centro de API de la organización para cumplir las reglas de estilo de API de las organizaciones. La linting genera un informe de análisis al que puede acceder en el centro de API. Use la linting y el análisis de API para detectar errores comunes e incoherencias en las definiciones de API.

Información general del escenario

En este escenario, analizará las definiciones de API en el centro de API mediante el motor de linting de código abierto Spectral. Una aplicación de Azure Functions ejecuta el motor de linting en respuesta a eventos del centro de API. Spectral comprueba que las API definidas en un documento de especificación JSON o YAML cumplan las reglas en una guía de estilo de API personalizable. Se genera un informe de cumplimiento de API que puede ver en el centro de API.

En el diagrama siguiente se muestran los pasos para habilitar la linting y el análisis en el centro de API.

1. Implemente una aplicación de Azure Functions que ejecute el motor de linting Spectral en una definición de API.

2. Configure una suscripción de eventos en un centro de API de Azure para desencadenar la aplicación de funciones.

3. Un evento se desencadena agregando o reemplazando una definición de API en el centro de API.

4. Al recibir el evento, la aplicación de funciones invoca el motor de linting Spectral.

5. El motor de linting comprueba que las API definidas en la definición se ajusten a la guía de estilo de API de la organización y genera un informe.

6. Vea el informe de análisis en el centro de API.

Opciones para implementar el motor de linting y la suscripción a eventos

En este artículo se proporcionan dos opciones para implementar el motor de linting y la suscripción a eventos en el centro de API:

• Implementación automatizada: use Azure Developer CLI (azd) para la implementación en un solo paso de la infraestructura de linting. Se recomienda esta opción para un proceso de implementación optimizado.

• Implementación manual: siga las instrucciones paso a paso para implementar la aplicación de Azure Functions y configurar la suscripción a eventos. Se recomienda esta opción si prefiere implementar y administrar los recursos manualmente.

Limitaciones

• Actualmente, la linting solo admite archivos de especificación JSON o YAML, como documentos de especificación OpenAPI o AsyncAPI.
• De manera predeterminada, el motor de linting usa el conjunto de reglas spectral:oas integrado. Para ampliar el conjunto de reglas o crear guías de estilo de API personalizadas, consulte el Repositorio de GitHub de Spectral.
• La aplicación de funciones de Azure que invoca la linting se cobra por separado, y usted la administra y mantiene.

Requisitos previos

• Un centro de API en la suscripción de Azure. Si aún no ha creado uno, consulte Inicio rápido: Creación del centro de API.

• El proveedor de recursos de Event Grid registrado en la suscripción. Si necesita registrar el proveedor de recursos de Event Grid, consulte Suscripción a eventos publicados por un asociado con Azure Event Grid.

• Para la CLI de Azure:

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

    

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

    • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

    • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

    • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

  Nota:

  Los comandos az apic requieren la extensión apic-extension CLI de Azure. Si no ha utilizado comandos az apic, la extensión se instala dinámicamente cuando ejecuta su primer comando az apic. Obtenga más información sobre las extensiones de la CLI de Azure.

  Nota:

  Los ejemplos de comandos de la CLI de Azure de este artículo se pueden ejecutar en PowerShell o en un shell de Bash. Cuando sea necesario debido a una sintaxis de variable diferente, se proporcionan ejemplos de comandos independientes para los dos shells.

Implementación de azd de la aplicación de Azure Functions y suscripción a eventos

En esta sección se proporcionan pasos automatizados mediante Azure Developer CLI para configurar la aplicación de Azure Functions y la suscripción a eventos que habilitan la linting y el análisis en el centro de API. También puede configurar los recursos manualmente.

Otros requisitos previos para esta opción

• Azure Developer CLI (azd)

Ejecución del ejemplo mediante azd

1. Clone el Repositorio de GitHub y ábralo en Visual Studio Code.

2. Cambie el directorio a la carpeta APICenter-Analyzer del repositorio.

3. En la carpeta resources/rulesets, puede encontrar un archivo oas.yaml. Este archivo refleja la guía de estilo de API actual y se puede modificar en función de las necesidades y requisitos de su organización.

4. Autentíquese con Azure Developer CLI y la CLI de Azure mediante los siguientes comandos:

   azd auth login
   
   az login
   

5. Ejecute el comando siguiente para implementar la infraestructura de linting en la suscripción de Azure.

   azd up
   

6. Siga las indicaciones para proporcionar la información y la configuración de implementación necesarias, como el nombre del entorno y el nombre del centro de API. Para obtener más información, consulte Ejecución del ejemplo mediante Azure Developer CLI (azd).

   Nota:

   La implementación puede tardar unos minutos.

7. Una vez completada la implementación, vaya al centro de API en Azure Portal. En el menú de la izquierda, seleccione Eventos>Suscripciones a eventos para ver la suscripción a eventos que se creó.

Ahora puede cargar un archivo de definición de API en el centro de API para desencadenar la suscripción a eventos y ejecutar el motor de linting.

Pasos manuales para configurar la aplicación de Azure Functions y la suscripción a eventos

En esta sección se proporcionan los pasos de implementación manuales para configurar la aplicación a Azure Functions y la suscripción a eventos para habilitar el linting y el análisis en el centro de API. También puede usar Azure Developer CLI para la implementación automatizada.

Otros requisitos previos para esta opción

• Visual Studio Code con la extensión v1.10.4 de Azure Functions o posterior.

Paso 1. Implementación en la aplicación de Azure Functions

Para implementar la aplicación de Azure Functions que ejecuta la función de linting en las definiciones de API:

1. Clone el Repositorio de GitHub y ábralo en Visual Studio Code.

2. En la carpeta resources/rulesets, puede encontrar un archivo oas.yaml. Este archivo refleja la guía de estilo de API actual y se puede modificar en función de las necesidades y requisitos de su organización.

3. De manera opcional, ejecute la aplicación de funciones localmente para probarla. Para obtener más información, consulte el archivo README en el repositorio.

4. Implemente la aplicación de funciones en Azure. Para ver los pasos, consulte Inicio rápido: Creación de una función en Azure con TypeScript mediante Visual Studio Code.

   Nota:

   La implementación de la aplicación de funciones puede tardar unos minutos.

5. Inicie sesión en Azure Portal y vaya a la aplicación de funciones.

6. En la página Información general, compruebe los detalles siguientes:

   • Confirme que el Estado de la aplicación de funciones sea En ejecución.
   • En Funciones, confirme que el Estado de la función apicenter-analyzer sea Habilitado.

   

Paso 2. Configuración de la identidad administrada en la aplicación de funciones

Para permitir que la aplicación de funciones acceda al centro de API, configure una identidad administrada para la aplicación de funciones. En los pasos siguientes se muestra cómo habilitar y configurar una identidad administrada asignada por el sistema para la aplicación de funciones mediante Azure Portal o la CLI de Azure.

Portal

1. En Azure Portal, vaya a la aplicación de funciones y seleccione Identidad en la sección Configuración.
2. En la pestaña Sistema asignado, cambie el Estado a Habilitado y, a continuación, seleccione Guardar.

Ahora que la identidad administrada está habilitada, asígnele el rol Administrador de cumplimiento del Centro de API de Azure para acceder al centro de API.

1. En Azure Portal, vaya al centro de API y seleccione Control de acceso (IAM).
2. Seleccione + Agregar > Agregar asignación de roles.
3. Seleccione roles de función de trabajo y, a continuación, seleccione Administrador de cumplimiento de Centro de API de Azure. Seleccione Siguiente.
4. En la página Miembros, en Asignar acceso a, seleccione Identidad administrada > + Seleccionar miembros.
5. En la página Seleccionar identidades administradas, busque y seleccione la identidad administrada de la aplicación de funciones. Haga clic en Seleccionar y, a continuación, en Siguiente.
6. Revise la asignación de roles y seleccione Revisar y asignar.

CLI de Azure

1. Habilite la identidad asignada por el sistema de la aplicación de funciones mediante el comando az functionapp identity assign. Reemplace <function-app-name> y <resource-group-name> por el nombre de la aplicación de funciones y el nombre del grupo de recursos. El siguiente comando almacena el identificador de entidad de seguridad de la identidad administrada asignada por el sistema en la variable 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. Obtenga el identificador de recurso del centro de API. Sustituya <apic-name> y <resource-group-name> por el nombre del centro de API y el nombre del 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. Asigne la identidad administrada de la aplicación de funciones al rol Administrador de cumplimiento del Centro de API de Azure en el centro de API mediante el 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 
   

Paso 3. Configuración de la suscripción de eventos en el centro de API

Ahora cree una suscripción de eventos en el centro de API para desencadenar la aplicación de funciones cuando se cargue o actualice un archivo de definición de API. En los pasos siguientes se muestra cómo crear la suscripción de eventos mediante Azure Portal o la CLI de Azure.

Portal

1. En Azure Portal, vaya al centro de API y seleccione Eventos.

2. En la pestaña Comenzar, seleccione Azure Function.

3. En la página Crear suscripción de eventos, realice los siguientes pasos:

   1. Escriba un Nombre descriptivo para la suscripción de eventos y seleccione Esquema de Event Grid.

   2. En Detalles del tema, escriba un Nombre de tema del sistema que prefiera.

   3. En Tipos de eventos, seleccione los siguientes eventos:

      • Definición de API agregada
      • Definición de API actualizada

   4. En Detalles del punto de conexión, seleccione Función de Azure > Configurar un punto de conexión.

   5. En la página Seleccionar función de Azure, seleccione la aplicación de funciones y la función apicenter-linter que configuró. Haga clic en Confirmar selección.

   6. Seleccione Crear.

      

4. Seleccione la pestaña Suscripciones de eventos y seleccione Actualizar. Confirme que el Estado de aprovisionamiento de la suscripción de eventos sea Correcto.

   

CLI de Azure

1. Obtenga el identificador de recurso del centro de API. Sustituya <apic-name> y <resource-group-name> por el nombre del centro de API y el nombre del 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. Obtenga el identificador de recurso de la función en la aplicación de funciones. En este ejemplo, el nombre de la función es apicenter-analyzer. Sustituya <function-app-name> y <resource-group-name> por el nombre de la aplicación de funciones y el nombre del 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. Cree una suscripción de eventos mediante el comando az eventgrid event-subscription create. La suscripción creada incluye eventos para agregar o actualizar las definiciones 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
   

   La salida del comando muestra los detalles de la suscripción de eventos. También puede obtener detalles mediante el comando az eventgrid event-subscription show. Por ejemplo:

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

Nota:

La suscripción a eventos puede tardar un breve tiempo en propagarse a la aplicación de funciones.

Desencadenamiento de eventos en el centro de API

Para probar la suscripción de eventos, pruebe a cargar o actualizar un archivo de definición de API asociado a una versión de API en el centro de API. Por ejemplo, cargue un documento OpenAPI o AsyncAPI. Una vez desencadenada la suscripción de eventos, la aplicación de funciones invoca el motor de linting de API para analizar la definición de la API.

• Para obtener pasos detallados para agregar una API, una versión de API y una definición de API al centro de API, consulte Tutorial: Registro de API en el centro de API.
• Para crear una API mediante la carga de un archivo de definición de API mediante la CLI de Azure, consulte Registro de API desde un archivo de especificación.

Para confirmar que se desencadenó la suscripción de eventos:

1. Vaya al centro de API y seleccione Eventos en el menú de la izquierda.

2. Seleccione la pestaña Suscripciones de eventos y seleccione la suscripción de eventos de la aplicación de funciones.

3. Revise las métricas para confirmar que se desencadenó la suscripción de eventos y que la linting se invocó correctamente.

   

   Nota:

   Las métricas pueden tardar unos minutos en aparecer.

Después de analizar la definición de API, el motor de linting genera un informe basado en la guía de estilo de API configurada.

Visualización de informes de análisis de API

Puede ver el informe de análisis de la definición de API en Azure Portal. Después de analizar una definición 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 portal, también puede ver un resumen de los informes de análisis de todas las definiciones de API del centro de API.

Informe de análisis de una definición de API

Para ver el informe de análisis de una definición de API en el centro de API:

1. En el portar, vaya a la versión de la API en el centro de API donde agregó o actualizó una definición de API.
2. En el menú de la izquierda, en Detalles, seleccione Definiciones.
3. Seleccione la definición de API que cargó o actualizó.
4. Seleccione la pestaña Análisis.

Se abre el Informe de análisis de API y muestra la definición de API y los errores, las advertencias y la información en función de la guía de estilo de API configurada. En la captura de pantalla siguiente se muestra un ejemplo de un informe de análisis de API.

Resumen del análisis de API

Para ver un resumen de los informes de análisis de todas las definiciones de API en el centro de API:

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.

   

Contenido relacionado

Obtener más información sobre Event Grid:

• Temas del sistema en Azure Event Grid
• Entrega de inserción de Event Grid: conceptos
• Esquema de Event Grid para Azure API Center