Controllo delle versioni semantico
L'API Google Ads segue il controllo delle versioni semantico con un numero di versione principale e uno secondario. Le versioni sono scritte come MAJOR.MINOR o vMAJOR.MINOR.
Ad esempio, v26.0 (o v26) è una versione principale, mentre v26.1 è una versione secondaria.
Per informazioni dettagliate sulle versioni attuali e precedenti, consulta le note di rilascio.
Versioni principali
Le versioni di release principali introducono modifiche che provocano errori e incompatibili con le versioni precedenti. La release iniziale di una versione principale termina con zero (vX.0 o vX, dove X è il numero della versione principale).
Ogni versione principale ha un percorso endpoint REST e gRPC separato (vX), che non include il suffisso della versione secondaria. Nel seguente URL, X è il numero della versione principale (ad esempio, v26):
https://googleads.googleapis.com/vX
Se esegui l'upgrade da una versione principale precedente, il codice potrebbe richiedere modifiche quando passi all'endpoint della nuova versione principale. Se utilizzi le nostre librerie client, esegui l'upgrade alla versione della libreria client che supporta la nuova versione principale. Quando viene rilasciata una versione principale, forniamo una guida all'upgrade per aiutarti a risolvere eventuali modifiche che provocano un errore nel codice.
Ecco alcuni esempi di modifiche che provocano un errore:
- Rimozione o ridenominazione di un servizio, un'interfaccia, un campo, un metodo o un valore enum.
- Modifica del tipo di un campo.
- Modifica del formato del nome di una risorsa.
- Modifica del formato dell'URL nella definizione HTTP.
- Modifica dei formati di output, ad esempio la modifica dei valori predefiniti.
- Modifica del motivo dell'errore restituito da A a B.
Versioni secondarie
Le versioni secondarie introducono solo modifiche compatibili con le versioni precedenti. Per una versione secondaria,
vMAJOR.MINOR ha un numero MINOR maggiore di zero (ad esempio,
v26.1).
Quando viene rilasciata una versione secondaria, l'endpoint della versione principale esistente (https://googleads.googleapis.com/vX) viene aggiornato automaticamente in loco. Tutte le chiamate API a una versione principale specifica vengono sempre indirizzate alla versione secondaria corrispondente più recente e l'API Google Ads non supporta le chiamate a versioni secondarie specifiche.
Non è necessario modificare il percorso della versione negli URL degli endpoint e il codice esistente continua a funzionare senza interruzioni. La durata delle versioni secondarie non viene monitorata separatamente. Le versioni secondarie condividono la stessa data di ritiro della versione principale corrispondente.
Le versioni secondarie aggiungono funzionalità o aggiornamenti che non influiscono sul codice esistente. Per utilizzare campi o funzionalità di una versione secondaria con una libreria client, esegui l'upgrade della libreria client a una release che includa le definizioni della versione secondaria.
Ritiro e dismissione
L'API Google Ads mantiene sempre attive più versioni principali. Periodicamente, le versioni precedenti vengono ritirate e successivamente disattivate:
- Deprecata: una versione è considerata deprecata solo se è contrassegnata esplicitamente come deprecata. Le chiamate API alle versioni ritirate continuano a essere eseguite correttamente fino alla data di ritiro.
- Ritiro: una versione viene disattivata alla data di ritiro e tutte le chiamate API al suo endpoint non vanno a buon fine.
Pubblichiamo annunci sul blog per sviluppatori prima del ritiro delle versioni. Consulta la pianificazione del ritiro e della deprecazione per conoscere le date di attivazione, deprecazione e ritiro pianificato.