Registrare le API nel centro API usando GitHub Actions

Questo articolo illustra come configurare un flusso di lavoro Di base di GitHub Actions per registrare un'API nel centro API dell'organizzazione. La registrazione si verifica quando un file di specifica dell'API viene aggiunto a un repository GitHub.

L'uso di un flusso di lavoro di GitHub Actions per registrare le API nel centro API offre un processo CI/CD coerente e ripetibile per ogni API nuova o aggiornata. Il flusso di lavoro può essere esteso per includere passaggi come l'aggiunta di metadati alla registrazione dell'API.

Il diagramma seguente illustra come la registrazione API nel centro API può essere automatizzata con un flusso di lavoro di GitHub Actions.

Il processo include i passaggi seguenti:

1. Configurare un flusso di lavoro di GitHub Actions nel repository che viene attivato quando viene unita una richiesta pull che aggiunge un file di definizione API.
2. Creare un ramo dal ramo principale nel repository GitHub.
3. Aggiungere un file di definizione dell'API, eseguire il commit delle modifiche ed eseguire il push nel nuovo ramo.
4. Creare una richiesta pull per unire il nuovo ramo nel ramo principale.
5. Unire la richiesta pull.
6. L'unione attiva un flusso di lavoro di GitHub Actions che registra l'API nel centro API.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. È possibile creare un centro API seguendo la procedura descritta in Avvio rapido: Creare il centro API (portale di Azure).

• Autorizzazioni per creare un'entità servizio nel tenant di Microsoft Entra ID.

• Un account GitHub e un repository GitHub in cui è possibile configurare i segreti e i flussi di lavoro di GitHub Actions.

• Per la CLI di Azure:

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

    

  • Se si preferisce, per eseguire localmente i comandi di riferimento CLI, installare l'interfaccia della riga di comando di Azure per eseguire i relativi comandi di riferimento. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

    • Installare l'estensione CLI di Azure al primo utilizzo quando richiesto. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

  Nota

  I comandi az apic richiedono l'estensione Azure CLI apic-extension. L'estensione può essere installata in modo dinamico quando si esegue il primo az apic comando oppure è possibile installare l'estensione manualmente. Per altre informazioni, vedere Gestire le estensioni dell'interfaccia della riga di comando di Azure: Installare, aggiornare e rimuovere.

  Per le modifiche e gli aggiornamenti più recenti in apic-extension, vedere le note sulla versione. Alcune funzionalità potrebbero richiedere un'anteprima o una versione specifica dell'estensione.

Configurare un flusso di lavoro di GitHub Actions

In questa sezione viene configurato il flusso di lavoro di GitHub Actions per questo scenario:

• Creare un'entità servizio da usare per le credenziali di Azure nel flusso di lavoro.
• Aggiungere le credenziali come segreto nel repository GitHub.
• Configurare un flusso di lavoro di GitHub Actions che viene attivato quando viene unita una richiesta pull che aggiunge un file di definizione API. Il file YAML del flusso di lavoro include un passaggio che usa l'interfaccia della riga di comando di Azure per registrare l'API nel centro API dal file di definizione.

Impostare un segreto dell'entità servizio

I passaggi seguenti creano un principale del servizio Microsoft Entra ID, usato per aggiungere credenziali al flusso di lavoro per autenticarsi con Azure.

Creare un'entità servizio usando il comando az ad sp create-for-rbac. Nell'esempio seguente viene prima usato il comando az apic show per recuperare l'ID risorsa del centro API. L'entità servizio viene quindi creata con il ruolo Collaboratore al servizio del Centro API di Azure per il centro 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

Copiare l'output JSON, simile all'esempio seguente:

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

Aggiungere l'entità servizio come segreto GitHub

Dopo aver ottenuto l'entità servizio, aggiungerla come segreto GitHub.

1. In GitHub esplorare il repository e selezionare Impostazioni nella barra dei menu in alto.

2. Nel riquadro di spostamento a sinistra in Sicurezza selezionare Segreti e variabili>Azioni

3. Seleziona Nuovo segreto del repository.

4. Nel campo Segreto, incolla l'intero output JSON dal comando CLI di Azure. Per Nome immettere AZURE_CREDENTIALS. Selezionare Aggiungi segreto.

   Il segreto è elencato in i segreti del repository.

   

Quando si configura il file del workflow di GitHub in seguito, si utilizza il segreto per l'input creds dell'azione di Azure/login. Ad esempio:

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

Aggiungere il file del flusso di lavoro al repository GitHub

Un flusso di lavoro di GitHub Actions viene specificato in un file di definizione YAML (.yml). Questa definizione contiene i vari passaggi e i parametri che costituiscono il flusso di lavoro. Per altre informazioni, vedere Sintassi del flusso di lavoro per GitHub Actions.

Nell'esempio seguente viene fornito un file di flusso di lavoro di base che è possibile usare o modificare.

• Il flusso di lavoro viene attivato quando una richiesta pull che aggiunge una definizione JSON nel APIs percorso viene chiusa nel ramo principale.

• Il percorso della definizione viene estratto dalla richiesta pull usando uno script GitHub, autenticato con il token GitHub predefinito.

• Le credenziali di Azure salvate nel repository vengono usate per accedere ad Azure.

• Il comando az apic register registra l'API nel centro API specificato nelle variabili di ambiente.

Seguire questa procedura per configurare il file del flusso di lavoro:

1. Copiare e salvare il file con un nome, ad esempio register-api.yml.

2. Confermare o aggiornare il nome della cartella del repository (APIs) in cui si prevede di aggiungere il file di definizione dell'API.

3. Aggiungere questo file del flusso di lavoro nel percorso /.github/workflows/ nel repository GitHub.

4. Impostare le variabili di AzioniSERVICE_NAME e RESOURCE_GROUP nel repository per il nome del centro API e il nome del gruppo di risorse in Azure.

Ecco il file del flusso di lavoro di esempio:

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 }}

Aggiungere il file di definizione dell'API al repository

Testare il flusso di lavoro aggiungendo un file di definizione API al repository. Seguire questi passaggi generali, che sono tipici di un flusso di lavoro di sviluppo. Per informazioni dettagliate sull'uso dei rami GitHub, vedere Informazioni sui modelli di sviluppo collaborativi nella documentazione di GitHub.

1. Creare un nuovo ramo di lavoro dal ramo principale nel repository.

2. Aggiungere il file di definizione dell'API al repository nel percorso APIs. Ad esempio: APIs/catfacts-api/07-15-2024.json.

3. Eseguire il commit delle modifiche ed effettuarne il push sul ramo di lavoro.

4. Creare una richiesta pull per unire il ramo di lavoro nel ramo principale.

5. Dopo la revisione, unire la richiesta pull. L'unione attiva il flusso di lavoro di GitHub Actions che registra l'API nel centro API.

   

Verificare la registrazione dell'API

Verificare che l'API sia registrata nel centro API.

1. Nel portale di Azure passare al centro API.

2. Nel riquadro di spostamento a sinistra espandere la sezione Inventario e selezionare Asset.

3. Verificare che l'API appena registrata venga visualizzata nell'elenco.

Aggiungere una nuova versione dell'API

È possibile aggiungere una nuova versione a un'API esistente nel centro API seguendo la stessa procedura con una leggera modifica.

1. Passare allo stesso ramo di lavoro nel repository o creare un nuovo ramo di lavoro.

2. Aggiungere un nuovo file di definizione API al repository nel percorso APIs, nella cartella per un'API esistente. Ad esempio, se in precedenza è stata aggiunta una definizione dell'API Cat Facts, aggiungere una nuova versione, ad esempio APIs/catfacts-api/07-22-2024.json.

3. Eseguire il commit delle modifiche ed effettuarne il push sul ramo di lavoro.

4. Creare una richiesta pull per unire il ramo di lavoro nel ramo principale.

5. Dopo la revisione, unire la richiesta pull. L'unione attiva il flusso di lavoro di GitHub Actions che registra la nuova versione dell'API nel centro API.

6. Nel portale di Azure passare al centro API e verificare che la nuova versione per l'API sia registrata.

Estendere lo scenario

È possibile estendere il flusso di lavoro di GitHub Actions per includere altri passaggi, ad esempio l'aggiunta di metadati per la registrazione dell'API. Ad esempio:

1. Usando lo schema dei metadati nel centro API, creare un file JSON di metadati per applicare i valori dei metadati alla registrazione API.

   Ad esempio, se lo schema dei metadati include proprietà come approver, team e cost center, un file JSON di metadati potrebbe essere simile al seguente:

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

2. Caricare un file JSON di metadati nella cartella per ogni API nel repository.

3. Aggiungere un passaggio del flusso di lavoro per applicare i metadati alla registrazione dell'API usando il comando az apic api update . Nell'esempio seguente l'ID API e il file di metadati vengono passati nelle variabili di ambiente, che verranno impostate altrove nel file del flusso di lavoro.

   [...]
   - 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 }}
   

Contenuto correlato

• Segreti in GitHub Actions
• Sintassi del flusso di lavoro per GitHub Actions