Controllo delle versioni

Alcune API Business Profile sono disponibili in più versioni e canali di rilascio. La versione è il segmento dell'URL della richiesta che segue il nome host, ad esempio v1 o v1alpha. In questa pagina viene spiegato come vengono numerate le versioni, quanto è stabile ogni canale di rilascio e come chiamare il canale alpha.

Numerazione delle versioni

Ogni versione dell'API ha un numero di versione principale e un suffisso facoltativo del canale:

  • Versione principale (v1, v2, …): una versione stabile, con disponibilità generale. Una versione principale riceve solo modifiche compatibili con le versioni precedenti, come nuovi metodi, nuovi campi o nuovi valori enum. Le modifiche non compatibili con le versioni precedenti vengono rilasciate in una nuova versione principale.
  • Canale alpha (v1alpha, v2alpha, …): un canale di pre-release di una versione principale. Include tutto ciò che è presente nella versione principale, oltre alle funzionalità che non hanno ancora raggiunto la disponibilità generale.

Canali di rilascio

Canale Stabilità Sommario
Disponibilità generale (v1) Stabile. Le modifiche all'interno di una versione principale sono compatibili con le versioni precedenti. Quando una versione principale viene ritirata, rimane disponibile per almeno 12 mesi dopo l'annuncio del ritiro. I ritiri e le date di ritiro vengono pubblicati nella pagina Programma di ritiro. Funzionalità in disponibilità generale.
Alpha (v1alpha) Pre-release, senza impegno di stabilità e senza durata definita. Le funzionalità alfa possono essere modificate o non essere più disponibili con un preavviso di almeno 30 giorni. Non utilizzare le funzionalità alfa nelle integrazioni di produzione. Tutto ciò che è incluso in v1, oltre alle funzionalità che non hanno ancora raggiunto la disponibilità generale.

Come vengono spostate le funzionalità tra i canali

Quando una funzionalità passa da v1alpha a v1, rimane disponibile in v1alpha.

Le guide e le pagine di riferimento per le funzionalità disponibili solo in v1alpha sono contrassegnate come alpha. Le nuove funzionalità alfa e in disponibilità generale, nonché le modifiche o le rimozioni delle funzionalità alfa, vengono annunciate negli Ultimi aggiornamenti e nel log delle modifiche di ogni API.

Utilizza il canale alpha

Per chiamare il canale alpha, sostituisci v1 con v1alpha nell'URL della richiesta. Ad esempio:

GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}

Entrambi i canali appartengono alla stessa API, quindi condividono quanto segue:

  • Abilitazione delle API nella console Google Cloud.
  • Ambiti OAuth 2.0 e requisiti di accesso.
  • Nomi delle risorse, ad esempio locations/{locationId}.
  • Quota. Le richieste a v1 e v1alpha vengono conteggiate ai fini della stessa quota per progetto. Per maggiori dettagli, consulta Limiti di quota.
  • I dati aziendali sottostanti. Le modifiche apportate tramite v1alpha sono visibili tramite v1 e viceversa.

Le librerie client e la directory delle API pubbliche includono solo v1. Per chiamare v1alpha, invia richieste REST direttamente.

Best practice

  • Utilizza la versione stabile, ad esempio v1, per le integrazioni di produzione.
  • Utilizza il canale alpha, ad esempio v1alpha, per adottare nuove funzionalità prima che raggiungano la disponibilità generale. Per condividere un feedback, consulta la pagina di assistenza.
  • Fai in modo che il tuo client tolleri i campi e i valori enum che non riconosce.
  • Prima di creare una funzionalità alfa, consulta la guida e il log delle modifiche per conoscere le limitazioni note.