La versione v1beta dell'API Merchant è stata ritirata e disattivata il 28 febbraio 2026. Per i passaggi per eseguire la transizione all'ultima versione stabile, consulta Eseguire la migrazione dalla v1beta alla v1.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Esegui la migrazione dei prodotti

L'API Merchant introduce un modo più solido e intuitivo per gestire i dati di prodotto. La modifica principale è la separazione dei dati di prodotto in due risorse distinte: ProductInput per l'invio dei dati e Product per la visualizzazione della versione finale elaborata, inclusi lo stato e i problemi del prodotto. Questa nuova struttura offre un'esperienza più prevedibile e trasparente.

Questa guida illustra le differenze principali per aiutarti a eseguire la migrazione dell'integrazione dall'API Content for Shopping. Per una guida dettagliata sull'utilizzo delle nuove funzionalità, vedi Gestire i prodotti.

Differenze principali

Di seguito sono riportate le modifiche più significative al modo in cui gestisci i prodotti nell'API Merchant rispetto all'API Content for Shopping:

Risorse dedicate per i dati di input e quelli elaborati: l'API Merchant suddivide la gestione dei prodotti in due risorse. Puoi utilizzare la risorsa ProductInput per inserire, aggiornare ed eliminare i dati di prodotto. Puoi utilizzare la risorsa Product di sola lettura per visualizzare il prodotto finale dopo che Google elabora gli input, applica le regole e combina i dati provenienti da origini supplementari.
Codifica per i nomi dei prodotti: puoi utilizzare la codifica base64url senza padding (RFC 4648, sezione 5) per i campi ProductInput.name e Product.name. Se i nomi dei prodotti contengono caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL, la codifica è obbligatoria. Ad esempio, devi codificare i nomi dei prodotti se contengono uno dei seguenti caratteri:
```
% . + / : ~ , ( * ! ) & ? = @ # $
```
Stato del prodotto integrato: il servizio productstatuses viene rimosso. I problemi di convalida dei prodotti e gli stati delle destinazioni sono ora inclusi direttamente nella risorsa Product all'interno del campo productStatus, semplificando il recupero dei dati.
Aggiornamenti di prodotto prevedibili: il nuovo metodo productInputs.patch modifica direttamente un input di prodotto specifico. Si tratta di un miglioramento significativo rispetto all'API Content for Shopping, in cui gli aggiornamenti potevano essere sovrascritti in modo imprevisto da altri caricamenti di feed. Nell'API Merchant, un aggiornamento rimane finché l'input del prodotto specifico non viene aggiornato di nuovo o eliminato. Gli aggiornamenti dei prodotti vengono applicati alla risorsa ProductInput anziché alla risorsa Product> elaborata.
Scegli l'origine dati per una gestione più pulita dei dati: tutte le operazioni di scrittura productInputs ora richiedono un parametro di query dataSource, che indica esplicitamente l'origine dati che stai modificando. Ciò è particolarmente utile se disponi di più origini che forniscono dati.
Nuovi identificatori di risorse: ora i prodotti vengono identificati da una risorsa RESTful name anziché dal campo id. Il formato è accounts/{account}/products/{product}.
Nessun batch personalizzato: il metodo custombatch non è più disponibile. Puoi utilizzare le richieste asincrone o il raggruppamento in batch HTTP per inviare più richieste in una singola chiamata HTTP.

Linee guida per le origini dati durante la migrazione

Prima di eseguire la migrazione delle origini dati, ti consigliamo vivamente di scegliere la strategia per le origini dati.

Per garantire una migrazione senza problemi ed evitare problemi come il furto di offerte, segui questi consigli:

Esegui il backfill del database: anziché chiamare dataSources.list prima di ogni operazione sul prodotto, ti consigliamo vivamente di eseguire un backfill una tantum del database locale. Aggiungi un campo nome dataSource a ogni record di prodotto per poter fornire l'identificatore corretto direttamente nelle tue richieste.
Consolidare e utilizzare le origini dati per qualsiasi etichetta e lingua: l'API Merchant consente di creare un'origine dati senza specificare l'etichetta e la lingua e quindi consente di inserire prodotti con qualsiasi etichetta e lingua dell'origine dati. Valuta la possibilità di utilizzare una sola origine dati per qualsiasi etichetta e lingua.
Proteggi i tuoi prodotti: se utilizzi regole per le origini dati, chiama products.get per trovare l'dataSource esatto associato a un prodotto prima di aggiornarlo o eliminarlo. In questo modo, modifichi la fonte prevista ed eviti il furto accidentale di offerte.

Richieste

Questa sezione confronta i formati delle richieste per l'API Content for Shopping e l'API Merchant.

Descrizione della richiesta	API Content per Shopping	API Merchant
Ottieni un prodotto	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}`
Elenca prodotti	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products`
Inserisci un prodotto	`POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products`	`POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert`
Aggiornare un prodotto	`PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}`
Elimina un prodotto	`DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}`
Ottenere lo stato del prodotto	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}`
Elenca gli stati del prodotto	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products`
Batch di più richieste	`POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch`	Utilizzare richieste asincrone o raggruppamento in batch HTTP

Identificatori

Il formato degli identificatori di prodotto è stato modificato nell'API Merchant in un nome di risorsa REST standard.

Descrizione dell'identificatore	API Content per Shopping	API Merchant
ID prodotto	Una stringa composta da segmenti separati dai due punti (`:`). Formato: `channel:contentLanguage:targetCountry:offerId` o `channel:contentLanguage:feedLabel:offerId`. Esempio: `online:en:US:sku123`	Una stringa di risorse REST `name`. Formato: `accounts/{account}/products/{product}` dove `{product}` è `contentLanguage~feedLabel~offerId`. Esempio: `accounts/12345/products/en~US~sku123`. Codifica: codifica base64url senza padding consigliata e obbligatoria in caso di ID prodotto che contengono caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL.

Metodi

Questa tabella mostra i metodi dell'API Content for Shopping e i relativi equivalenti nell'API Merchant.

Metodo API Content for Shopping	Metodo dell'API Merchant	Disponibilità e note
`products.get`	`products.get`	Recupera il prodotto finale elaborato.
`products.list`	`products.list`	Elenca i prodotti finali elaborati.
`products.insert`	`productInputs.insert`	Inserisce un input del prodotto. Richiede un `dataSource`.
`products.update`	`productInputs.patch`	Il comportamento è notevolmente diverso. Aggiorna un input specifico del prodotto ed è persistente.
`products.delete`	`productInputs.delete`	Elimina un input di prodotto specifico. Richiede un `dataSource`.
`products.custombatch`	Non disponibile	Utilizza richieste asincrone o raggruppamento in batch HTTP.
`productstatuses.get`	`products.get`	Il servizio `productstatuses` viene rimosso. Le informazioni sullo stato ora fanno parte della risorsa `Product`.
`productstatuses.list`	`products.list`	Il servizio `productstatuses` viene rimosso. Le informazioni sullo stato ora fanno parte della risorsa `Product`.
`productstatuses.custombatch`	Non disponibile	Utilizza le richieste asincrone o il raggruppamento in batch HTTP.

Modifiche dettagliate dei campi

Questa tabella mette in evidenza i campi importanti che sono stati modificati, aggiunti o rimossi nell'API Merchant.

API Content per Shopping	API Merchant	Descrizione
`id`	`name`	L'identificatore principale di un prodotto è ora la risorsa REST `name`. Codifica base64url senza padding consigliata e obbligatoria in caso di nomi di prodotto che contengono caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL.
Attributi della specifica dei dati di prodotto di primo livello (ad es. `title`, `price`, `link`)	`productAttributes` oggetto	Gli attributi prodotto come `title`, `price` e `link` non sono più campi di primo livello. Ora sono raggruppati all'interno dell'oggetto `productAttributes` nelle risorse `Product` e `ProductInput`. In questo modo, la struttura delle risorse è più pulita e organizzata.
`targetCountry`	`feedLabel`	Il nome della risorsa ora utilizza `feedLabel` anziché `targetCountry` per allinearsi alla funzionalità di Merchant Center.
`feedId`	`dataSource` (parametro di query)	Il nome `dataSource` è ora un parametro di query obbligatorio per tutti i metodi di scrittura `productInputs` (`insert`, `update`, `delete`).
`channel`	Non disponibile. Utilizza `legacy_local` solo per i prodotti locali.	Il campo `channel` non è più presente nell'API Merchant. I prodotti con il canale `LOCAL` nell'API Content for Shopping devono invece impostare il campo `legacy_local` su true.
Non disponibile	`versionNumber`	Un nuovo campo facoltativo in `ProductInput` che può essere utilizzato per impedire inserimenti fuori ordine nelle origini dati principali.
Campi di tipo `string` con un insieme di valori definito	Campi di tipo `enum` con un insieme di valori definito	I campi all'interno degli attributi di prodotto con un insieme di valori definito (ad esempio `excluded_destinations`, `availability`) ora sono di tipo `enum`.

Indietro

Migrate online return policy management

Avanti

Migrate reporting management