Migrazione dalla versione v1beta alla versione v1

Questa guida ti aiuta a eseguire la migrazione dall'API Merchant v1beta alla versione v1, la prima disponibile a livello generale. La versione 1 introduce diversi aggiornamenti e alcune modifiche che potrebbero richiedere aggiornamenti del codice. Queste modifiche sono progettate per semplificare l'API e migliorare la gestione del tuo account Merchant Center.

Differenze principali

Ecco le modifiche più importanti da tenere presenti quando esegui la migrazione da v1beta a v1:

• Registrazione una tantum di almeno uno sviluppatore API per utilizzare l'API Merchant: dovrai chiamare il metodo registerGcp (solo una volta per ogni progetto Google Cloud utilizzato per l'autenticazione) per fornire i tuoi dati di contatto, che ti consentono di utilizzare l'API e di ricevere aggiornamenti e annunci relativi all'API Merchant. Non potrai utilizzare alcuna API v1 o v1alpha finché questo passaggio non sarà completato. Per le istruzioni, vedi Registrarsi come sviluppatore.
• Product.attributes rinominato: il campo Product.attributes è stato rinominato in Product.productAttributes.
• Rimozione delle informazioni fiscali a livello di prodotto:i campi taxes e taxCategory sono stati rimossi dall'oggetto Product.productAttributes. Per maggiori informazioni, consulta l'articolo del Centro assistenza Google Merchant Center sulle imposte.
• Modifiche al campo GTIN: il campo gtin nell'oggetto Product.productAttributes è stato rinominato in gtins per riflettere meglio il fatto che può contenere più valori. Il campo gtin nell'oggetto OrderTrackingSignals.lineItemDetails ora è un array ed è stato rinominato anche in gtins.
• Rimozione del campo Canale:il campo channel è stato rimosso da prodotti, input di prodotto e origini dati. È stato introdotto un nuovo campo booleano, legacyLocal, per indicare chiaramente i prodotti venduti esclusivamente nei negozi fisici. Nota: il campo legacyLocal è un campo ausiliario per facilitare la migrazione e verrà ritirato una volta che i metodi di marketing online e locale potranno essere completamente mirati con una singola origine prodotto. Per ulteriori informazioni, consulta la tabella nella sezione seguente.
• Nuovi campi per gli attributi dell'inventario regionale e locale:
  • Tutti i campi RegionalInventory ad eccezione di name, account e region sono ora inclusi in un nuovo oggetto chiamato regionalInventoryAttributes . Ad esempio, l'attributo RegionalInventory.price ora si trova in RegionalInventory.regionalInventoryAttributes.price.
  • Tutti i campi LocalInventory ad eccezione di name, account e storeCode sono ora inclusi in un nuovo oggetto chiamato localInventoryAttributes . Ad esempio, l'attributo LocalInventory.price ora si trova in LocalInventory.localInventoryAttributes.price.
• Rimozione di customAttributes dagli inventari regionali e locali: il campo customAttributes è stato rimosso dalle risorse RegionalInventory e LocalInventory.
• Creazione di account perfezionata: il campo ridondante users è stato rimosso da CreateAndConfigureAccountRequest. Utilizza il campo user singolare per associare un utente iniziale a un nuovo account.
• Alcuni tipi di attributo sono stati modificati da stringhe a enumerazioni:alcuni campi all'interno delle risorse Product e Inventory con un elenco ristretto di valori definiti sono stati modificati dal tipo string al tipo enum per una migliore convalida dei dati (ad esempio, il campo Product.ProductAttributes.condition ora è un enum).
• Rimozione del metodo di aggiornamento delle norme sui resi online:il metodo onlineReturnPolicy.update viene rimosso in v1. Crea una norma sui resi online utilizzando il metodo onlineReturnPolicy.create.

Come eseguire la migrazione

Il ritiro della versione v1beta dell'API Merchant è previsto per il 28 febbraio 2026. Per ulteriori informazioni sulla pianificazione del ritiro, consulta la guida al controllo delle versioni dell'API Merchant.

• Il primo passaggio della migrazione consiste nell'eseguire una registrazione una tantum come sviluppatore (vedi Registrarsi come sviluppatore). Devi chiamare il metodo registerGcp per ogni progetto Google Cloud che utilizzi per l'autenticazione prima che qualsiasi metodo v1 funzioni.

• Indipendentemente dal modo in cui chiami le API (con REST, gRPC o utilizzando le librerie client), puoi eseguire la migrazione in più fasi. Ciò significa che puoi aggiornare e migrare il codice un'API alla volta (ad esempio, spostando l'API Products su v1 mantenendo l'API Accounts su v1beta) senza dover aggiornare l'intera integrazione contemporaneamente.

Modifiche dettagliate ai campi

Questa tabella fornisce un confronto dettagliato dei campi modificati tra le versioni v1beta e v1.

v1beta	v1	Descrizione
Product.gtin	Product.gtins	Il campo per i GTIN è stato rinominato.
Product.taxes	Rimosso	Il campo taxes è stato rimosso
Product.taxCategory	Rimosso	Il campo taxCategory è stato rimosso
Product.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il campo legacyLocal per i casi d'uso locali.
Product.attributes	Product.productAttributes	Il campo attributes è stato rinominato in productAttributes.
availability, condition, gender, includedDestinations e excludedDestinations nei campi Product sono rappresentati come strings (o array di strings)	Questi campi ora sono enums (o array di enums)	I campi con un elenco ristretto di valori definiti sono stati modificati dal tipo string a enum.
price, salePrice, salePriceEffectiveDate e availability in RegionalInventory	Spostato in RegionalInventory.regionalInventoryAttributes	Questi campi sono stati spostati in regionalInventoryAttributes.
Il campo RegionalInventory.availability è un string	RegionalInventory.regionalInventoryAttributes.availability è ora un enums	Il tipo di disponibilità è cambiato da string a enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla e instoreProductLocation in LocalInventory	Spostato in LocalInventory.localInventoryAttributes	Questi campi sono stati spostati in localInventoryAttributes.
Il campo LocalInventory.availability è un string	LocalInventory.localInventoryAttributes.availability è ora un enums	Il tipo di disponibilità è cambiato da string a enum.
LocalInventory.customAttributes	Rimosso	Gli attributi personalizzati non sono più supportati per l'inventario locale.
RegionalInventory.customAttributes	Rimosso	Gli attributi personalizzati non sono più supportati per l'inventario regionale.
ProductInput.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il campo legacyLocal per i casi d'uso locali.
DataSource.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il campo legacyLocal per i casi d'uso locali.
Non disponibile	ProductInput.legacyLocal	Un nuovo campo booleano per indicare che un prodotto può avere come target solo metodi di marketing locali. L'ID risorsa prodotto avrà il prefisso "local~".
Non disponibile	Product.legacyLocal	Un nuovo campo booleano per indicare che un prodotto viene venduto solo nei negozi locali e non è disponibile per l'acquisto online.
Non disponibile	DataSource.legacyLocal	Un nuovo campo booleano per indicare che un'origine dati contiene prodotti venduti solo in negozi locali.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Il campo gtin è stato rinominato in gtins ed è ora un array di stringhe (anziché una stringa).
CreateAndConfigureAccountRequest.users	Rimosso	Il campo users è stato rimosso. Utilizza il campo user per aggiungere l'amministratore iniziale all'account.