Come gestire la configurazione di gestione API con la CLI APIOps

SI APPLICA A: Tutti i livelli di Gestione API

APIOps CLI è uno strumento di configuration-as-code per Gestione API di Azure. In questo articolo, lo usi per estrarre la configurazione di API Management in artefatti locali, esaminare gli artefatti in Git, anteprima le modifiche e pubblicare artefatti approvati su un'istanza di API Management. La CLI può anche scaffoldare file GitHub Actions o Azure Pipelines per un flusso di lavoro APIOps.

I passaggi forniscono un flusso di lavoro minimo che puoi validare con un'istanza di gestione API non in produzione. Per orientamenti su architettura e design, vedi Implementazioni API automatizzate con APIOps.

Usa questo flusso di lavoro per:

  • Rivedi definizioni API, policy e altre configurazioni di gestione API tramite pull request.
  • Tieni una cronologia auditabile delle modifiche di configurazione approvate.
  • Promuovi artefatti revisionati tra ambienti di gestione API.
  • Inizia con una configurazione estratta da un'istanza esistente oppure crea nel codice artefatti compatibili con la CLI.

APIOps CLI completa gli approcci DevOps per le API descritti in Usare DevOps e CI/CD per pubblicare le API. Valuta la CLI e il flusso di lavoro degli artefatti che intendi in un ambiente non produttivo prima di usarlo per le implementazioni in produzione.

Prerequisiti

  • Node.js versione 22 o successiva.
  • interfaccia della riga di comando di Azure, per i passaggi di autenticazione locale in questo articolo.
  • Un abbonamento Azure e un'istanza di gestione API non produttiva esistente.
  • Un repository Git per i tuoi artefatti di gestione API.
  • Un'identità con accesso all'istanza di gestione API. La guida per l'avvio della CLI APIOps elenca i ruoli di Contributore e Lettoredel Servizio di Gestione API all'ambito delle risorse di gestione API per il suo flusso di lavoro di estrazione e pubblicazione.

Per l'automazione della produzione, usa identità separate e con privilegi minimi quando possibile. Un'identità di estrazione necessita di accesso in lettura all'istanza sorgente. Un'identità di pubblicazione necessita solo dei permessi necessari per aggiornare l'istanza di destinazione.

Installa la CLI APIOps

Installare il pacchetto npm @azure-tools/apiops-cli:

npm install -g @azure-tools/apiops-cli

Verificare la versione installata:

apiops --version

Registra e fissa la versione che approvi per le tue pipeline CI/CD. Rivedi il changelog della CLI APIOps prima di aggiornare.

Autenticazione con Azure

Per l'uso locale, accedi con interfaccia della riga di comando di Azure e seleziona l'abbonamento che contiene la tua istanza di gestione API non in produzione:

az login
az account set --subscription <subscription-id>

La CLI APIOps utilizza DefaultAzureCredential. Oltre alle credenziali interfaccia della riga di comando di Azure, supporta credenziali ambientali, identità di carico di lavoro, identità gestita, Azure PowerShell e credenziali CLI per sviluppatori Azure.

Per CI/CD, è preferibile usare la federazione dell'identità del carico di lavoro o l'identità gestita invece di un segreto client. Non inserire mai credenziali, access token, chiavi di abbonamento o valori segreti nominati nel controllo del fonte. Per le opzioni di autenticazione supportate, consulta la guida all'autenticazione della CLI APIOps.

Prepara un deposito di artefatti

Esegui i comandi API CLI dalla radice del repository Git che contiene i tuoi artefatti di gestione API.

Per generare le pipeline e i modelli di configurazione per GitHub Actions, esegui:

apiops init --ci github-actions --environments dev,prod --non-interactive

Per Azure Pipelines, usare:

apiops init --ci azure-devops --environments dev,prod --non-interactive

Il comando crea definizioni di pipeline, un modello di filtro di estrazione, modelli di override per l'ambiente, indicazioni per la configurazione dell'identità e una directory apim-artifacts. Rivedi ogni file generato prima di fare commit o abilitare una pipeline. Non usare --force in un repository che contiene già file, a meno di non aver prima esaminato i file che il comando sovrascrive.

Se hai già un repository e una pipeline progettata, puoi invece creare o selezionare una directory di artefatti e usare direttamente i comandi estrazione e pubblicazione.

Crea gli artefatti iniziali

Scegli uno dei seguenti approcci per stabilire gli artefatti che il tuo repository possiede.

Estrazione della configurazione esistente

Per creare una base da un'istanza di gestione API esistente, estrarne la configurazione:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

Il comando crea file informativi JSON, file di policy XML e file di specifiche API in una gerarchia sotto apim-artifacts. Per un'istanza grande, configura un filtro di estrazione in modo che il repository gestisca solo le risorse previste.

Inizia con gli artefatti code-first

Per un flusso di lavoro centrato sul codice, aggiungere una specifica OpenAPI e le informazioni e file di policy necessari per la gestione delle API utilizzando il formato artefatto della CLI APIOps. Non dare per scontato che una struttura di un repository applicativo esistente o un file OpenAPI, di per sé, siano pronti per apiops publish.

Se sei nuovo al formato artefatto, estrai prima una piccola API di riferimento da un'istanza non in produzione. Usa i file risultanti come modelli e consulta le linee guida sul flusso di lavoro code-first.

Esamina gli artefatti

Prima di pubblicare:

  1. Ispeziona i file generati o creati manualmente e conferma che il repository contenga solo le risorse che intendi gestire.
  2. Esamina specifiche API, policy, backend, valori nominati, prodotti e le loro dipendenze.
  3. Rimuovi i valori specifici dell'ambiente che non dovrebbero essere trasferiti in un altro ambiente. Usa file di override dell'ambiente verificati o riferimenti ad Azure Key Vault, ove appropriato.
  4. Cerca credenziali e valori segreti. L’estrazione oscura i campi segreti supportati e i modelli di criteri riconosciuti, ma potrebbe non rilevare ogni segreto incorporato. Non commettere segreti o valori irrisolti *** REDACTED *** .
  5. Esegui il commit degli artefatti in un ramo e utilizza una pull request per la convalida e l'approvazione.

Anteprima di una pubblicazione

Eseguire un dry run sull'istanza di destinazione non di produzione. Una prova generale riporta creazioni, aggiornamenti e cancellazioni pianificate senza applicarli:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Rivedi l'output e risolvi cambiamenti imprevisti o dipendenze mancanti. Un test di successo non sostituisce il test del comportamento dell'API, delle policy, dei permessi o della connettività backend.

Caution

Non aggiungere --delete-unmatched al tuo primo flusso di lavoro. Quell'opzione elimina risorse nell'istanza target che non sono rappresentate negli artefatti sorgente.

Pubblica i reperti recensiti

Dopo che la pull request è stata approvata e l'esecuzione di prova è riuscita, pubblica gli stessi artefatti revisionati nella destinazione non di produzione:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Valida le API e le policy nell'istanza di destinazione dopo la pubblicazione. Quando automatizzi questo flusso di lavoro, configura la pipeline per pubblicare un commit approvato e proteggi gli ambienti di distribuzione con i controlli e le approvazioni richieste dalla tua organizzazione.

Passaggi successivi

  • Ultimo aggiornamento: