Registrare le API nel centro API usando GitHub Actions

Questo articolo illustra come configurare un flusso di lavoro di base GitHub Actions per registrare un'API nel centro API dell'organizzazione quando viene aggiunto un file di specifiche API 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 usando un flusso di lavoro di GitHub Actions.

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. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il centro API.

• Autorizzazioni per creare un'entità servizio nel tenant 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 l'interfaccia della riga di comando di Azure:

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. 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 Accedere tramite l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare 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 dell'interfaccia della riga di comando di Azure apic-extension. Se non sono stati usati comandi az apic, l'estensione può essere installata in modo dinamico quando si esegue il primo comando az apic oppure è possibile installarla manualmente. Altre informazioni sulle estensioni dell'interfaccia della riga di comando di Azure.

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

  Nota

  Gli esempi di comandi dell'interfaccia della riga di comando di Azure riportati in questo articolo possono essere eseguiti in PowerShell o in una shell bash. Se necessario, a causa di una sintassi di variabile diversa, vengono forniti esempi di comandi separati per le due shell.

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.

Configurare un segreto dell'entità servizio

Nei passaggi seguenti creare un'entità servizio Microsoft Entra ID, che verrà usata per aggiungere credenziali al flusso di lavoro per l'autenticazione con Azure.

Nota

La configurazione di un'entità servizio viene visualizzata a scopo dimostrativo. Il modo consigliato per eseguire l'autenticazione con Azure per GitHub Actions è OpenID Connect, un metodo di autenticazione che usa token di breve durata. La configurazione di OpenID Connect con GitHub Actions è più complessa, ma offre sicurezza avanzata. Ulteriori informazioni

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.

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 "Azure API Center Service 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 "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

Copiare l'output JSON, simile al 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

1. In GitHub esplorare il repository. Seleziona Impostazioni.

2. In Sicurezzaselezionare Segreti e variabili>Azioni

3. Selezionare Nuovo segreto repository.

4. Incollare l'intero output JSON del comando dell'interfaccia della riga di comando di Azure nel campo del valore del segreto. Assegnare al segreto il nome AZURE_CREDENTIALS. Selezionare Aggiungi segreto.

   Il segreto è elencato in Segreti repository.

   

Quando in seguito si configura il file del flusso di lavoro GitHub, si usa il segreto come creds di input dell'azione di accesso di Azure. 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 è rappresentato da un file di definizione YAML (.yml). Questa definizione contiene i vari passaggi e i parametri che costituiscono il flusso di lavoro. Ulteriori informazioni

Di seguito è riportato un file del flusso di lavoro di base per questo esempio che è possibile usare o modificare.

In questo esempio:

• Il flusso di lavoro viene attivato quando una richiesta pull che aggiunge una definizione JSON nel percorso APIs viene chiusa nel ramo principale.
• Il percorso della definizione viene estratto dalla richiesta pull usando uno script GitHub, che viene 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.

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 aggiungerà il file di definizione dell'API.
3. Aggiungere questo file del flusso di lavoro nel percorso /.github/workflows/ nel repository GitHub.
4. Impostare le variabiliSERVICE_NAME Actions e RESOURCE_GROUP nel repository per il nome del centro API e il nome del gruppo di risorse in Azure.

Suggerimento

Usando l'estensione Visual Studio Code per Centro API di Azure, è possibile generare un file del flusso di lavoro iniziale eseguendo un comando di estensione. Nel riquadro comandi selezionare Centro API di Azure: registrare API. Selezionare CI/CD>GitHub. È quindi possibile modificare o estendere il file per lo scenario in uso.

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 di GitHub, vedere la 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 eseguirne il push nel 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 andare al Centro API.
2. Nel menu a sinistra, in Assetselezionare API.
3. Verificare che l'API appena registrata venga visualizzata nell'elenco delle API.

Aggiungere una nuova versione dell'API

Per aggiungere una nuova versione a un'API esistente nel centro API, seguire i passaggi precedenti, 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 eseguirne il push nel 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 andare al centro API e verificare che la nuova versione 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": "diego@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

• Uso dei segreti in GitHub Actions
• Creazione di variabili di configurazione per un repository