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 un errore 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. Non è necessario modificare il percorso della versione negli URL degli endpoint e il codice esistente continua a funzionare senza interruzioni.
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
Periodicamente, le versioni precedenti dell'API Google Ads vengono ritirate e successivamente dismesse:
- Ritirata: quando viene rilasciata una versione principale (ad esempio
v26), tutte le versioni principali precedenti vengono contrassegnate come ritirate. Le chiamate API alle versioni deprecate continuano ad avere esito positivo fino alla data di ritiro e le release delle librerie client esistenti continuano a supportarle, anche se le release delle librerie client successive omettono le versioni API deprecate per ridurre le dimensioni del pacchetto. - 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 del ritiro definitivo per le date di attivazione, ritiro e ritiro definitivo pianificato.