Guida al controllo delle versioni di Compute Engine: API, librerie client e strumenti

Questa guida spiega come Compute Engine gestisce le versioni nelle API REST, nelle librerie client e nello strumento a riga di comando gcloud. Descrive la differenza tra il controllo delle versioni basato sul canale (CBV) e il controllo delle versioni basato sull'interfaccia (IBV), concentrandosi principalmente su quest'ultimo.

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Seleziona la scheda relativa a come prevedi di utilizzare i campioni in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi Google Cloud e alle API, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

      gcloud init

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  • Imposta una regione e una zona predefinite.

    • REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Controllo delle versioni basato sul canale e controllo delle versioni basato sull'interfaccia

L'API Compute Engine supporta due schemi di controllo delle versioni: il controllo delle versioni basato sui canali (CBV) e il controllo delle versioni basato sulle interfacce (IBV).

  • Nel controllo delle versioni basato sul canale, le release sono di lunga durata e ricevono aggiornamenti in loco. Compute Engine supporta i canali v1, beta e alpha.

  • Nel controllo delle versioni basato sull'interfaccia, le singole interfacce, i metodi e le risorse sono versionati e possono evolvere in modo incrementale e indipendente.

L'IBV sostituisce il CBV. Tuttavia, le implementazioni esistenti di CBV non sono interessate dall'introduzione di IBV e dalle nuove versioni. Puoi continuare a utilizzare CBV se preferisci rimanere sulla release dell'API esistente.

IBV ti aiuta a verificare che il comportamento dell'API e il relativo payload di richiesta e risposta siano conformi a una versione dell'API prevista. Utilizzi IBV specificando una versione dell'API nella richiesta, utilizzando un parametro di query o un'intestazione. Per saperne di più, consulta Crea una richiesta API.

L'utilizzo della verifica dell'identità offre i seguenti vantaggi:

  • Maggiore stabilità: IBV protegge le applicazioni in esecuzione dalle modifiche consentendoti di indicare la versione dell'API a cui il servizio deve rispondere.
  • Controllo dell'adozione delle modifiche:con IBV, scegli la versione che serve la tua richiesta. In questo modo puoi eseguire l'upgrade alle nuove funzionalità del servizio in base al tuo programma.

Per saperne di più sulle strategie di controllo delle versioni, consulta la proposta di miglioramento dell'API 185.

Policy di controllo delle versioni basata sull'interfaccia

Ogni release dell'API Compute Engine IBV è una raccolta di modifiche all'interfaccia che condividono la stessa versione del servizio, anche se le interfacce potrebbero cambiare versione in modo indipendente.

L'API Compute Engine IBV supporta le versioni stabili e di anteprima.

Versioni stabili

La maggior parte delle release API sono versioni stabili. Le versioni stabili mantengono una compatibilità rigorosa, come definito in AIP-180, il che significa che le versioni stabili più recenti della stessa versione non interrompono le funzionalità esistenti né richiedono la riscrittura del codice.

Compute Engine identifica le versioni API stabili utilizzando date standard nel formato YYYY-MM-DD (ad esempio 2026-09-01). Le date successive indicano le versioni più recenti.

Compute Engine supporta versioni stabili per periodi di tempo prolungati, in modo che i tuoi sistemi di produzione rimangano affidabili e ininterrotti. Per la maggior parte delle applicazioni, è necessario utilizzare una sola versione stabile per eseguire le attività quotidiane.

Versioni di anteprima

Compute Engine può rilasciare versioni di anteprima per raccogliere feedback anticipati degli utenti sulle nuove funzionalità. Le uscite in anteprima aggiungono un tag -preview alla data (ad esempio 2026-10-01-preview).

Le versioni di anteprima includono tutte le funzionalità dell'ultima release stabile, oltre a funzionalità sperimentali appena aggiunte. Quando utilizzi le versioni di anteprima, tieni presente quanto segue:

  • Le funzionalità di anteprima non garantiscono la compatibilità con le versioni precedenti o future.
  • Non è consigliabile utilizzare le versioni di anteprima per gli ambienti di produzione mission critical.
  • Potremmo modificare, perfezionare o rimuovere le funzionalità di anteprima durante la promozione a una versione stabile.

Utilizza le versioni di anteprima quando vuoi sperimentare nuove funzionalità e pianifica di aggiornare il codice quando viene lanciata una versione stabile.

Specificare una versione dell'API nella richiesta

Per effettuare chiamate API utilizzando IBV, le richieste specificano una versione di destinazione utilizzando un parametro di query o un'intestazione. Per esempi su come effettuare richieste API, consulta Creare una richiesta API.

Librerie client cloud

Le librerie client cloud eliminano l'onere di creare e analizzare le chiamate REST non elaborate. Ogni release della libreria si connette direttamente a una versione specifica dell'API basata sulla data.

Per accedere alle nuove funzionalità, aggiorna il pacchetto delle librerie client di Cloud all'ultima versione. Pubblichiamo le librerie client Cloud aggiornate insieme alle nuove release stabili e di anteprima delle API.

Ti consigliamo di eseguire le applicazioni di produzione su librerie client di Cloud stabili, isolando le librerie di anteprima negli ambienti di test.

Google Cloud CLI (gcloud)

La CLI gcloud ti consente di gestire le risorse Compute Engine senza dover monitorare manualmente i singoli endpoint REST.

La CLI gcloud divide i comandi in due categorie:

  • Comandi stabili:i comandi standard (ad esempio gcloud compute instances create) hanno come target le versioni stabili dell'API. Questi comandi sono completamente supportati, prevedibili e consigliati per gli script di produzione.
  • Comandi di anteprima: le funzionalità di accesso in anteprima utilizzano il gruppo gcloud preview (ad esempio gcloud preview compute ...). Questi comandi mostrano un breve avviso perché i contratti possono cambiare prima della release finale.

Terraform

Il provider Terraform Google Cloud astra il controllo delle versioni delle API e gestisce le interazioni API sottostanti. Le configurazioni Terraform non espongono né richiedono impostazioni manuali dell'intestazione della versione.

Per accedere alle nuove funzionalità, aggiorna il Google Cloud provider Terraform alla versione più recente. Per le funzionalità in anteprima, utilizza il provider google-beta.

Domande frequenti

Questa sezione risponde alle domande frequenti sul controllo delle versioni dell'API Compute Engine.

  • Devo eseguire la migrazione dalla versione 1 (CBV) all'IBV?

    No, le richieste API CBV v1 esistenti continuano a funzionare come prima. Tuttavia, non potrai accedere alle nuove funzionalità disponibili nell'API IBV.

  • Per quanto tempo verrà supportata una versione dell'API IBV?

    Le versioni stabili vengono mantenute per sempre in base alle norme sul ritiro standard Google Cloud.

  • Con quale frequenza vengono rilasciate nuove versioni dell'API IBV?

    Sono previste nuove versioni dell'API IBV con rilasci trimestrali. Le versioni di anteprima possono essere rilasciate in qualsiasi momento.

  • Devo attivare qualcosa nella console Google Cloud ?

    No, l'API IBV è abilitata per impostazione predefinita con l'API Compute Engine.

  • Cosa succede se non specifico una versione nella mia richiesta?

    La tua richiesta utilizza per impostazione predefinita l'endpoint CBV v1.

  • Dove posso trovare la versione dell'API nelle voci di Cloud Audit Logs?

    La versione dell'API viene registrata in protoPayload.requestMetadata.callerSuppliedUserAgent e nelle intestazioni o parametri di ricerca della richiesta.

Passaggi successivi

Per saperne di più sull'API Compute Engine, leggi i seguenti documenti: