Registro de API en el centro de API mediante Acciones de GitHub

En este artículo se muestra cómo configurar un flujo de trabajo básico de Acciones de GitHub para registrar una API en el Centro de API de la organización. El registro se produce cuando se agrega un archivo de especificación de API a un repositorio de GitHub.

El uso de un flujo de trabajo de Acciones de GitHub para registrar las API en el centro de API proporciona un proceso de CI/CD coherente y repetible para cada API nueva o actualizada. El flujo de trabajo se puede extender para incluir pasos como agregar metadatos al registro de API.

En el diagrama siguiente se muestra cómo el registro de API en el centro de API se puede automatizar con un flujo de trabajo de Acciones de GitHub.

El proceso incluye los pasos siguientes:

1. Configure un flujo de trabajo de Acciones de GitHub en el repositorio que se desencadene cuando se combina una solicitud de incorporación de cambios que agrega un archivo de definición de API.
2. Cree una rama desde la rama principal en el repositorio de GitHub.
3. Agregue un archivo de definición de API, confirme los cambios e insértelos en la nueva rama.
4. Cree un pull request para combinar la nueva rama en la rama principal.
5. Combine la solicitud de incorporación de cambios.
6. La combinación desencadena un flujo de trabajo de Acciones de GitHub que registra la API en el centro de API.

Requisitos previos

• Un centro de API en la suscripción de Azure. Puede crear un centro de API siguiendo el procedimiento de Inicio rápido: Creación del centro de API (Azure Portal).

• Permisos para crear una entidad de servicio en el inquilino de Microsoft Entra ID.

• Una cuenta de GitHub y un repositorio de GitHub en el que puede configurar secretos y flujos de trabajo de Acciones de GitHub.

• Para la CLI de Azure:

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Introducción a 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 Autenticación en Azure mediante 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 obtener más información sobre las extensiones, consulte Uso y administración 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 az apic comandos requieren la extensión de la apic-extension CLI de Azure. La extensión se puede instalar dinámicamente al ejecutar el primer az apic comando o puede instalar la extensión manualmente. Para más información, consulte Administración de extensiones de la CLI de Azure: Instalación, actualización y eliminación.

  Para ver los cambios y actualizaciones más recientes en apic-extension, consulte las notas de lanzamiento. Algunas características pueden requerir una versión preliminar o específica de la extensión.

Configuración de un flujo de trabajo de Acciones de GitHub

En esta sección, configurará el flujo de trabajo de Acciones de GitHub para este escenario:

• Cree una entidad de servicio que se usará para las credenciales de Azure dentro del flujo de trabajo.
• Agregue las credenciales como un secreto en el repositorio de GitHub.
• Configure un flujo de trabajo de Acciones de GitHub que se desencadene cuando se combine una solicitud de incorporación de cambios que agrega un archivo de definición de API. El archivo YAML de flujo de trabajo incluye un paso que usa la CLI de Azure para registrar la API en el centro de API desde el archivo de definición.

Configuración de un secreto de entidad de servicio

En los pasos siguientes se crea un principal de servicio de Microsoft Entra ID, que se usa para agregar credenciales al flujo de trabajo para autenticarse con Azure.

Cree un principal de servicio mediante el comando az ad sp create-for-rbac. En el ejemplo siguiente se usa primero el comando az apic show para recuperar el identificador de recurso del centro de API. A continuación, la entidad de servicio se crea con el rol de Colaborador del servicio Azure API Center para el Centro de API.

#! /bin/bash
apiCenter=<api-center-name>
resourceGroup=<resource-group-name>
spName=<service-principal-name>

apicResourceId=$(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

# PowerShell syntax
$apiCenter = "<api-center-name>"
$resourceGroup = "<resource-group-name>"
$spName = "<service-principal-name>"

$apicResourceId = $(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

Copie la salida JSON, que debería tener un aspecto similar al ejemplo siguiente:

{
  "clientId": "<GUID>",
  "clientSecret": "<GUID>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  [...other endpoints...]
}

Adición de la entidad de servicio como secreto de GitHub

Una vez tenga la entidad de servicio, agréguela como un secreto de GitHub:

1. En GitHub, examine el repositorio y seleccione Configuración en la barra de menús superior.

2. En el panel de navegación izquierdo en Seguridad, seleccione Secretos y variables>Acciones

3. Seleccione New repository secret (Nuevo secreto del repositorio).

4. En el campo Secreto , pegue toda la salida JSON del comando de la CLI de Azure. En Nombre, escriba AZURE_CREDENTIALS. Seleccione Add secret (Agregar secreto).

   El secreto aparece en Secretos del repositorio.

   

Cuando configure el archivo de flujo de trabajo de GitHub más adelante, usará el secreto para la entrada creds de la acción Azure/login. Por ejemplo:

- uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

Adición del archivo de flujo de trabajo al repositorio de GitHub

Se especifica un flujo de trabajo de Acciones de GitHub en un archivo de definición de YAML (.yml). En esta definición se incluyen los diversos pasos y parámetros que componen el flujo de trabajo. Para obtener más información, consulte Sintaxis de flujo de trabajo para Acciones de GitHub.

En el ejemplo siguiente se proporciona un archivo de flujo de trabajo básico que puede usar o modificar.

• El flujo de trabajo se desencadena cuando se cierra una solicitud de incorporación de cambios que agrega una definición JSON en la ruta APIs de la rama principal.

• La ubicación de la definición se extrae de la solicitud de incorporación de cambios mediante un script de GitHub, que se autentica con el token de GitHub predeterminado.

• Las credenciales de Azure guardadas en el repositorio se usan para iniciar sesión en Azure.

• El comando az apic register registra la API en el centro de API especificado en las variables de entorno.

Siga estos pasos para configurar el archivo de flujo de trabajo:

1. Copie y guarde el archivo con un nombre como register-api.yml.

2. Confirme o actualice el nombre de la carpeta del repositorio (APIs) donde planea agregar el archivo de definición de API.

3. Agregue este archivo de flujo de trabajo en la ubicación /.github/workflows/ en el repositorio de GitHub.

4. Establezca las variables de AccionesSERVICE_NAME y RESOURCE_GROUP en el repositorio para el nombre del Centro de API y el nombre del grupo de recursos en Azure.

Este es el archivo de flujo de trabajo de ejemplo:

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [ closed ]
    branches:
      - [ "main" ]
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
jobs:
  register:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v2
      
      - name: Get specification file path in the PR
        id: get-file-location
        uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const pull_number = context.payload.pull_request.number;
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const files = await github.rest.pulls.listFiles({
              owner,
              repo,
              pull_number
            });
            if (files.data.length === 1) {
              const filename = files.data[0].filename;
              core.exportVariable('API_FILE_LOCATION', filename);
              console.log(`API_FILE_LOCATION: ${{ env.API_FILE_LOCATION }}`);
            }
            else {
              console.log('The PR does not add exactly one specification file.');
            }

      - name: Azure login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Register to API Center
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az apic api register -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}

Adición del archivo de definición de API al repositorio

Pruebe el flujo de trabajo agregando un archivo de definición de API al repositorio. Siga estos pasos generales, que son típicos de un flujo de trabajo de desarrollo. Para más información sobre cómo trabajar con ramas de GitHub, consulte Acerca de los modelos de desarrollo de colaboración en la documentación de GitHub.

1. Cree una nueva rama de trabajo desde la rama principal del repositorio.

2. Agregue el archivo de definición de API al repositorio en la ruta APIs. Por ejemplo, APIs/catfacts-api/07-15-2024.json.

3. Confirme los cambios e insértelos en la rama de trabajo.

4. Cree una solicitud de incorporación de cambios para combinar la rama de trabajo en la rama principal.

5. Después de revisarlo, combine la solicitud de incorporación de cambios. La combinación desencadena el flujo de trabajo de las Acciones de GitHub que registra la API en el centro de APIs.

   

Comprobación del registro de API

Compruebe que la API está registrada en el Centro de API.

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

2. En el panel de navegación izquierdo, despliegue la sección Inventario y seleccione Bienes.

3. Compruebe que la API recién registrada aparece en la lista.

Adición de una nueva versión de API

Puede agregar una nueva versión a una API existente en el Centro de API siguiendo los mismos pasos con una ligera modificación.

1. Cambie a la misma rama de trabajo en el repositorio o cree una nueva rama de trabajo.

2. Agregue un nuevo archivo de definición de API al repositorio en la ruta de acceso APIs, en la carpeta de una API existente. Por ejemplo, si anteriormente agregó una definición de la API Cat Facts, agregue una nueva versión, como APIs/catfacts-api/07-22-2024.json.

3. Confirme los cambios e insértelos en la rama de trabajo.

4. Cree una solicitud de incorporación de cambios para combinar la rama de trabajo en la rama principal.

5. Después de revisarlo, combine la solicitud de incorporación de cambios. La combinación desencadena el flujo de trabajo de Acciones de GitHub que registra la nueva versión de API en el centro de API.

6. En Azure Portal, vaya al centro de API y confirme que la nueva versión de la API está registrada.

Ampliación del escenario

Puede ampliar el flujo de trabajo de Acciones de GitHub para incluir otros pasos, como agregar metadatos para el registro de API. Por ejemplo:

1. Con el esquema de metadatos del centro de API, cree un archivo JSON de metadatos para aplicar valores de metadatos al registro de API.

   Por ejemplo, si el esquema de metadatos incluye propiedades como approver, team y cost center, un archivo JSON de metadatos podría tener este aspecto:

   {
     "approver": "admin-user@contoso.com",
     "team": "Store API dev team",
     "costCenter": "12345"  
   }
   

2. Cargue un archivo JSON de metadatos en la carpeta para cada API del repositorio.

3. Agregue un paso de flujo de trabajo para aplicar los metadatos al registro de API mediante el comando az apic api update . En el ejemplo siguiente, el identificador de API y el archivo de metadatos se pasan en variables de entorno, que se establecerían en otro lugar del archivo de flujo de trabajo.

   [...]
   - name: Apply metadata to API in API Center
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az apic api update -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}
   

Contenido relacionado

• Secretos en Acciones de GitHub
• Sintaxis de flujo de trabajo para Acciones de GitHub