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 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 se puede automatizar el registro de API en el centro de API mediante un flujo de trabajo de Acciones de GitHub.

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 una solicitud de incorporación de cambios 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. Si aún no ha creado uno, consulte Inicio rápido: Creación del centro de API.

• 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 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 usado comandos az apic, la extensión se puede instalar dinámicamente al ejecutar el primer comando az apic o puede instalar la extensión manualmente. Obtenga más información sobre las extensiones de la CLI de Azure.

  Consulte las notas de la versión para obtener los cambios y actualizaciones más recientes de apic-extension.

  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.

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 en el 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, cree una entidad de servicio de Microsoft Entra ID, que se usará para agregar credenciales al flujo de trabajo para autenticarse con Azure.

Nota:

La configuración de una entidad de servicio se muestra con fines de demostración. La manera recomendada de autenticarse con Azure para Acciones de GitHub es con OpenID Connect, un método de autenticación que usa tokens de corta duración. La configuración de OpenID Connect con Acciones de GitHub es más compleja, pero ofrece seguridad reforzada. Más información

Cree una entidad 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 Colaborador del Centro de API.

Bash

#! /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 Contributor --scopes $apicResourceId --json-auth

PowerShell

# 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 Contributor --scopes $apicResourceId --json-auth

Copie la salida JSON, que debe tener un aspecto similar al 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

1. En GitHub, examine el repositorio. Haga clic en Configuración.

2. En Seguridad, seleccione Secretos y variables>Acciones

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

4. Pegue la salida JSON completa del comando de la CLI de Azure en el campo de valor del secreto. Asigne al secreto el siguiente nombre: 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

Un flujo de trabajo de Acciones de GitHub se representa mediante 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. Más información

A continuación se muestra un archivo de flujo de trabajo básico para este ejemplo que puede usar o modificar.

En este ejemplo:

• 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 de acceso APIs en 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.

Para configurar el archivo de flujo de trabajo:

1. Copie y guarde el archivo con un nombre como register-api.yml.
2. Actualice los valores de las variables de entorno para que coincidan con el centro de API en Azure.
3. Confirme o actualice el nombre de la carpeta del repositorio (APIs) donde agregará el archivo de definición de API.
4. Agregue este archivo de flujo de trabajo en la ruta de acceso /.github/workflows/ en el repositorio de GitHub.

Sugerencia

Con la extensión de Visual Studio Code para el Centro de API de Azure, puede generar un archivo de flujo de trabajo inicial mediante la ejecución de un comando de extensión. En la paleta de comandos, seleccione Centro de API de Azure: Registrar API. Seleccione CI/CD>GitHub. A continuación, puede modificar el archivo para su escenario.

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [closed]
    branches:
      - main
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
env:
  # set this to your Azure API Center resource group name
  RESOURCE_GROUP: <YOUR_RESOURCE_GROUP>
  # set this to your Azure API Center service name
  SERVICE_NAME: <YOUR_API_CENTER>
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', hfilename);
              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 ${{ env.RESOURCE_GROUP }} -n ${{ env.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 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 de acceso 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 la revisión, combine la solicitud de incorporación de cambios. La combinación desencadena el flujo de trabajo de Acciones de GitHub que registra la API en el centro de API.

   

Comprobación del registro de API

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

1. En Azure Portal vaya al centro de API.
2. En el menú de la izquierda, en Recursos, seleccione API.
3. Compruebe que la API recién registrada aparece en la lista de API.

Adición de una nueva versión de API

Para agregar una nueva versión a una API existente en el Centro de API, siga los pasos anteriores, 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 la revisión, 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 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": "diego@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 ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}
   

Contenido relacionado

• Uso de secretos en Acciones de GitHub
• Creación de variables de configuración para un repositorio