Eseguire la migrazione delle origini dati

Questa guida spiega come eseguire la migrazione dell'integrazione dai servizi datafeeds e datafeedstatuses dell'API Content for Shopping alla sub-API Origini dati nell'API Merchant. La nuova sub-API Data Sources offre un controllo più diretto sulle pipeline di dati e semplifica la gestione delle origini dati.

Per saperne di più sulle nuove funzionalità, consulta la guida Gestisci le origini dati.

Differenze principali

Rispetto all'API Content for Shopping, l'API Merchant offre diversi vantaggi:

• Creazione esplicita dell'origine dati. L'API non crea più automaticamente un'origine dati "API Content" al primo inserimento del prodotto. Nell'API Merchant, devi creare esplicitamente le origini dati prima di poter caricare i prodotti. In questo modo, avrai un maggiore controllo sull'organizzazione e sulla gestione delle pipeline di dati di prodotto fin dall'inizio.

• Supporto di più origini dati API. Nell'API Content for Shopping, eri limitato a un'unica origine dati "API Content" creata automaticamente. Con l'API Merchant puoi creare e gestire più origini dati del tipo di input API.

• Origini dati senza etichetta e lingua. L'API Merchant ti consente di creare un'origine dati principale senza specificare feedLabel e contentLanguage. Questo tipo di origine dati accetta i prodotti in qualsiasi combinazione di feedLabel e contentLanguage, il che semplifica i caricamenti dei prodotti per le integrazioni che non richiedono origini dati separate per regioni diverse.

• Target di dati semplificati. Ogni origine dati ora corrisponde a un singolo target, definito da una combinazione univoca di feedLabel e contentLanguage. I feed di destinazione con più dati sono deprecati nell'API Merchant.

• Stato di caricamento dei file dedicato. L'API Merchant rappresenta lo stato delle origini dati basate su file utilizzando una risorsa fileUploads di sola lettura separata. Per recuperare lo stato di un caricamento file, utilizza il metodo fileUploads.get con l'alias latest.

• Nuovi tipi di origini dati. La risorsa DataSource supporta più verticali, tra cui promozioni, inventario locale e inventario regionale, fornendo un modo unificato per gestire tutte le pipeline di dati.

• Origini dati automatiche. Con l'API Merchant, ora puoi attivare o disattivare la funzionalità Origini dati automatiche per il tuo account utilizzando il metodo autofeedSettings.updateAutofeedSettings nella sub-API Accounts. Per saperne di più, consulta Configura le impostazioni di Autofeed.

Scegli la strategia per l'origine dati

Hai tre opzioni per gestire le origini dati:

• Crea un'unica origine dati dell'API Merchant per qualsiasi etichetta del feed e lingua. Utilizza questa opzione per semplificare la gestione con un'unica origine dati che accetta prodotti con qualsiasi feedLabel e contentLanguage. Nella vecchia configurazione dell'API Content, definisci le regole per etichette e lingue specifiche tramite origini dati separate e inserisci i prodotti nell'origine dati con le regole target corrispondenti. Se scegli questa opzione, ti consigliamo di eseguire la migrazione di tutti i tuoi prodotti alla nuova origine dati e di rimuovere le origini dati dell'API Content una volta completata la migrazione di tutti i prodotti.

• Crea nuove origini dati dell'API Merchant per ogni etichetta e lingua. Utilizza questa opzione se devi supportare nuove combinazioni di feedLabel e contentLanguage (e preferisci mantenere una separazione rigorosa tra loro) o se utilizzi la configurazione delle regole dell'origine dati che si basa su feedLabel e contentLanguage specifici. Dovrai creare un'origine dati separata per ogni coppia di feedLabel e contentLanguage che utilizzi. Puoi combinare le origini dati dell'API Merchant con quelle create con l'API Content for Shopping.

Importante: quando scegli una delle opzioni precedenti per creare una nuova origine dati, potresti dover eseguire la migrazione delle regole esistenti. Le migrazioni delle regole non possono essere eseguite tramite l'API e devono essere eseguite manualmente nell'interfaccia utente di Merchant Center, il che potrebbe richiedere un po' di tempo per gli account avanzati in cui le regole vengono applicate direttamente a molti sub-account individuali.

• Mantieni le origini dati dell'API Content esistenti. Puoi continuare a utilizzare le origini dati create con l'API Content for Shopping, in quanto sono compatibili con l'API Merchant. Puoi trovare i nomi delle risorse utilizzando dataSources.list o nell'interfaccia utente di Merchant Center. Le origini dati principali dell'API Content supportano solo feedLabel e contentLanguage specifici con cui sono state create. Le origini dati dell'API Content vengono visualizzate in Merchant Center con l'origine "API Content" anche se i prodotti vengono inseriti utilizzando l'API Merchant. Puoi combinarle con nuove origini dati dell'API Merchant che hanno come target anche coppie feedLabel e contentLanguage specifiche.

Ti consigliamo di eseguire il backfill del database dei prodotti locali memorizzando i nomi di tutte le origini dati principali una volta per ciascuno dei tuoi prodotti per evitare chiamate dataSources.list ripetute.

Avviso: se utilizzi le regole dell'origine dati, per evitare il "furto di offerte" accidentale (spostamento di un prodotto nell'origine dati sbagliata), ti consigliamo di utilizzare products.get per identificare l'origine dati specifica associata a un prodotto prima di eseguire operazioni di scrittura.

Richieste

La tabella seguente mette a confronto i formati degli URL di richiesta tra l'API Content for Shopping e l'API Merchant.

Descrizione della richiesta	API Content per Shopping	API Merchant
Creare un'origine dati	POST https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds	POST https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources
Recupera un'origine dati	GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID}	GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}
Elenca le origini dati	GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds	GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources
Aggiorna un'origine dati	PUT https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID}	PATCH https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}
Eliminare un'origine dati	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID}	DELETE https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}
Recupera un'origine dati	POST https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID}/fetchNow	POST https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}:fetch
Ottieni lo stato dell'origine dati	GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeedstatuses/{DATAFEED_ID}	GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}/fileUploads/latest
Elenca gli stati delle origini dati	GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeedstatuses	Non disponibile. Utilizza dataSources.list e fileUploads.get per ogni origine dati basata su file.

Identificatori

L'API Merchant utilizza un nome della risorsa basato su stringhe come identificatore.

Descrizione dell'identificatore	API Content per Shopping	API Merchant
Identificatore dell'origine dati	datafeedId (numerico)	name (stringa, formato: accounts/{account}/dataSources/{datasource})

Metodi

Questa tabella confronta i metodi dei servizi datafeeds e datafeedstatuses dell'API Content for Shopping con i loro equivalenti nell'API Merchant.

Metodo API Content for Shopping	Metodo dell'API Merchant	Disponibilità e note
datafeeds.custombatch	Non disponibile	Utilizza invece chiamate API individuali.
datafeeds.delete	dataSources.delete	Disponibile
datafeeds.fetchnow	dataSources.fetch	Disponibile Questo metodo ora funziona solo per le origini dati con un file di input.
datafeeds.get	dataSources.get	Disponibile
datafeeds.insert	dataSources.create	Disponibile
datafeeds.list	dataSources.list	Disponibile
datafeeds.update	dataSources.update	Disponibile Utilizza la semantica PATCH anziché PUT.
datafeedstatuses.custombatch	Non disponibile	Utilizza invece chiamate API individuali. Per saperne di più, consulta Invia più richieste contemporaneamente.
datafeedstatuses.get	fileUploads.get	Disponibile per le origini dati basate su file. Utilizza l'alias latest per ottenere lo stato del caricamento più recente. Per altri tipi di origini dati, le informazioni sullo stato fanno parte della risorsa DataSource.
datafeedstatuses.list	Non disponibile	Per ottenere lo stato di più origini dati, elenca prima tutte le origini dati con dataSources.list. Poi chiama fileUploads.get con l'alias latest per ogni origine dati basata su file.

Modifiche dettagliate ai campi

Questa tabella mostra le modifiche a livello di campo tra le risorse Datafeed e DatafeedStatus nell'API Content for Shopping e le risorse DataSource e FileUpload nell'API Merchant.

API Content per Shopping	API Merchant	Descrizione
Datafeed	DataSource	La risorsa principale per la configurazione dell'origine dati.
id	name	L'identificatore della risorsa. Modificato da un ID numerico a un nome della risorsa stringa.
name	displayName	Il nome dell'origine dati rivolto agli utenti.
attributeLanguage	primaryProductDataSource.contentLanguage	Il codice lingua ISO 639-1 a due lettere degli elementi nell'origine dati.
fileName	fileInput.fileName	Il nome del file caricato. Questo campo è ora nidificato in fileInput.
fetchSchedule	fileInput.fetchSettings	La pianificazione per il recupero di un'origine dati basata su file. Ora è nidificato in fileInput.
fetchSchedule.paused	fileInput.fetchSettings.enabled	La logica è invertita. paused: true equivale a enabled: false.
format	Non disponibile	I campi fileEncoding, columnDelimiter e quotingMode vengono rimossi. Ora vengono rilevati automaticamente.
targets	primaryProductDataSource.feedLabel, primaryProductDataSource.contentLanguage e primaryProductDataSource.countries	Il campo targets ripetuto viene rimosso. Ora ogni origine dati ha un unico target definito da questi campi, il che riflette il ritiro dei feed con più target di dati.
DatafeedStatus	FileUpload	Lo stato di un caricamento di file è ora una risorsa di sola lettura separata.
datafeedId	name	L'identificatore del caricamento del file, che fa riferimento all'origine dati principale.
processingStatus	processingState	Lo stato di elaborazione del caricamento. I valori di stringa (success, failure, in progress) vengono sostituiti da un enum (SUCCEEDED, FAILED, IN_PROGRESS).
errors, warnings	issues	Gli errori e gli avvisi vengono uniti in un unico elenco issues. Ogni problema ha un campo severity (ERROR o WARNING).
lastUploadDate	uploadTime	Il timestamp dell'ultimo caricamento. Il formato è cambiato da una stringa a un oggetto Timestamp.
country, language e feedLabel	Non applicabile	Questi campi non sono più presenti nella risorsa di stato. Fanno parte della risorsa DataSource.
targets[].included_destinations, targets[].excluded_destinations	primaryProductDataSource.destinations	I due elenchi separati per le destinazioni incluse ed escluse vengono sostituiti da un unico elenco destinations. Ogni elemento del nuovo elenco è un oggetto che specifica la destinazione e il relativo stato (ENABLED o DISABLED), fornendo una configurazione più esplicita.