Scegli tra i feed dei file e l'API Merchant

Puoi caricare i dati di prodotto su Merchant Center utilizzando feed basati su file, l'API Merchant o una combinazione di entrambi:

  • Feed dei prodotti basati su file: carica file CSV, TSV o XML utilizzando SFTP, Google Cloud Storage, Fogli Google o recuperi programmati.
  • API Merchant: invia richieste programmatiche direttamente dal tuo backend per aggiornamenti incrementali man mano che i dati di prodotto cambiano, oltre a sincronizzazioni periodiche del catalogo completo.

Questa guida mette a confronto i due approcci, spiega quando utilizzare uno o l'altro (o entrambi insieme) e fornisce un playbook di migrazione passo passo se decidi di spostare alcuni o tutti i tuoi prodotti dai feed dei file all'API.

Scegli l'approccio all'origine dati

Valuta la volatilità del tuo catalogo, l'architettura di backend e i flussi di lavoro operativi per decidere se utilizzare l'API Merchant, i feed di file o una configurazione ibrida.

Quando utilizzare l'API Merchant

Utilizza un'origine dati principale API se:

  • Integrazione programmatica diretta: preferisci chiamare un'API direttamente dal tuo backend anziché generare file e gestire pipeline di trasferimento file (come SFTP o Google Cloud Storage).
  • Elevata volatilità dei prezzi e dell'inventario: i prezzi dei prodotti o i livelli di stock cambiano di frequente nel corso della giornata.
  • Aggiornamenti immediati in caso di modifiche ai dati: vuoi inviare le modifiche ai prodotti a Google non appena si verificano nel tuo backend, anziché attendere la generazione di file e il caricamento successivi programmati.
  • Aggiornamenti incrementali del catalogo: vuoi inserire, aggiornare o eliminare singoli prodotti man mano che cambiano, senza ricaricare ogni volta l'intero catalogo.
  • Aggiornamenti parziali degli attributi: vuoi aggiornare campi specifici di un prodotto (ad esempio price o availability utilizzando productInputs.patch) senza inviare nuovamente il payload completo del prodotto.

Quando utilizzare i feed di file

Utilizza un'origine dati principale basata su file se:

  • Catalogo statico: i dati di prodotto cambiano raramente (ad esempio, una volta al giorno o meno).
  • Backend solo snapshot senza monitoraggio delta: il tuo backend esporta solo snapshot completi del catalogo e non può monitorare le modifiche a livello di articolo o le eliminazioni esplicite dei prodotti.
  • Flussi di lavoro basati su fogli di lavoro: i team non tecnici curano o sostituiscono i dati di prodotto direttamente in Fogli Google o file CSV.
  • Operazioni a bassa manutenzione: preferisci un'esportazione di file pianificata in cui Merchant Center gestisce il recupero e l'elaborazione degli snapshot, anziché un'integrazione API con regolazione della frequenza delle richieste, gestione dei nuovi tentativi e sincronizzazioni periodiche del catalogo completo.

Quando utilizzare entrambi

Puoi combinare i feed di file e l'API Merchant nello stesso account Merchant Center nei seguenti scenari:

  • Cataloghi dei prodotti suddivisi: utilizzi l'API Merchant per i prodotti che cambiano rapidamente (ad esempio offerte lampo o inventario con un elevato turnover) e i feed di file per i segmenti di catalogo statici o le linee di prodotti separate. Assicurati che ogni prodotto venga caricato solo da un'origine dati principale (consulta Utilizzo parallelo e proprietà dell'origine dati principale).
  • Dati principali dell'API con feed supplementari basati su file: gestisci i dati di prodotto principali tramite un'origine dati principale dell'API, mentre i team non tecnici o i partner terzi forniscono attributi aggiuntivi tramite feed supplementari basati su file (come Fogli Google o file CSV) uniti alle regole degli attributi o viceversa.
  • Migrazione parziale o graduale: esegui la transizione di mercati, categorie o subaccount specifici all'API, mantenendo il resto del catalogo nei feed di file.

Se decidi di trasferire alcuni o tutti i tuoi prodotti dai feed dei file all'API Merchant, segui il playbook di migrazione passo passo.

Differenze principali nell'architettura

I feed di file e l'API Merchant basata su push differiscono nel modo in cui Google elabora e gestisce i dati di prodotto:

Concetto Feed di file API Merchant
Modello di integrazione Dump di file offline: esporti il catalogo in un file e lo trasferisci utilizzando SFTP, Google Cloud Storage, Fogli Google o recuperi programmati. Integrazione programmatica diretta: il tuo backend invia le richieste direttamente all'endpoint API.
Granularità delle mutazioni Elaborazione collettiva: la modifica di un elemento in genere richiede la rielaborazione dell'intero file. Transazioni granulari: puoi inserire, applicare patch o eliminare solo i prodotti che sono stati modificati.
Tempistiche di sincronizzazione Sincronizzazione in batch: le modifiche rimangono in attesa nel backend fino al successivo ciclo di esportazione e trasferimento dei file pianificato. Chiamate immediate o programmate: puoi inviare le modifiche incrementali immediatamente non appena si verificano, oltre alle sincronizzazioni complete periodiche.
Comportamento di eliminazione Implicita (istantanea): ogni file è un'istantanea completa; la rimozione di una riga dal file principale comporta l'eliminazione del prodotto. Esplicito: non esiste il concetto di snapshot; chiama productInputs.delete per rimuovere un prodotto non più disponibile.
Rappresentazione delle risorse Stato singolo: le righe del file rappresentano l'input non elaborato. Separazione dei dati non elaborati da quelli elaborati: l'API suddivide i dati in ProductInput (l'input non elaborato) e Product (lo stato elaborato finale).
Regole degli attributi (feed) Applicato alle colonne del file non elaborato nell'interfaccia utente di Merchant Center. Supportato nella UI di Merchant Center. Obbligatorio quando si uniscono i dati dell'API con file supplementari di terze parti; facoltativo per le trasformazioni da un'unica origine se gestite nel backend.

Utilizzo parallelo e proprietà dell'origine dati principale ("vince l'ultimo aggiornamento")

Sebbene sia possibile utilizzare sia i feed dei file sia l'API nello stesso account Merchant Center, ti consigliamo vivamente di utilizzare un solo metodo per inserire un determinato prodotto.

Merchant Center opera secondo un modello "vince l'ultimo aggiornamento". L'origine dati principale (API o feed di file) che ha inviato l'inserimento del prodotto più recente ottiene la proprietà principale dei dati di quel prodotto:

  • Quando l'origine dati del file è proprietaria del prodotto: l'omissione del prodotto da un caricamento di file successivo attiva l'eliminazione implicita, rimuovendo il prodotto da Merchant Center.
  • Quando l'origine dati API è proprietaria del prodotto: l'omissione del prodotto da un caricamento di file non ha alcun effetto perché il feed del file non è più proprietario del prodotto. Devi chiamare il numero accounts.productInputs.delete per rimuoverlo.
  • Rischio di riacquisizione accidentale della proprietà: se un feed di file aggiornato viene eseguito dopo un push dell'API e contiene il prodotto, l'origine dati del file riacquisisce la proprietà. Le successive omissioni dal file comporteranno l'eliminazione imprevista del prodotto.

Per evitare eliminazioni impreviste o la perdita di aggiornamenti dell'API, non eseguire aggiornamenti simultanei sugli stessi prodotti utilizzando sia l'API sia le origini dati principali dei file.

Considerazioni principali sulle API

Prima di iniziare l'implementazione, comprendi questi comportamenti critici dell'API Merchant:

Origini dati flessibili (senza lingua o etichetta)

A differenza dei feed di file che richiedono di definire in anticipo un'etichetta del feed di destinazione e una lingua specifiche, l'API Merchant consente di creare origini dati principali senza specificare un feedLabel o un contentLanguage.

  • Caricamenti flessibili: ti consente di caricare prodotti con qualsiasi combinazione di lingua o etichetta del feed in un'unica origine dati.
  • Gestione semplificata: non è necessario creare e gestire origini dati separate per ogni mercato di destinazione. Nota: per maggiori dettagli sulla scelta di una strategia per l'origine dati, consulta Scegli una strategia per l'origine dati.

Strategia di sincronizzazione e quote

A differenza di un feed di file in cui carichi l'intero catalogo in un unico batch, progetta l'integrazione dell'API Merchant in modo da includere sia gli aggiornamenti incrementali sia le sincronizzazioni complete ritmiche:

  • Combina gli aggiornamenti incrementali con le sincronizzazioni complete periodiche: invia richieste productInputs.insert o productInputs.patch man mano che gli attributi del prodotto cambiano nel backend. Poiché l'affidamento esclusivo sugli aggiornamenti incrementali può causare la perdita di sincronizzazione dei dati nel tempo, esegui anche sincronizzazioni complete periodiche per riconciliare il catalogo con la fonte di riferimento (che aggiorna anche la scadenza dei prodotti di 30 giorni). La frequenza con cui esegui una sincronizzazione completa dipende dalle dimensioni del catalogo e dalla quota API disponibile.
  • Scagliona le richieste per rispettare le quote dell'API: non chiamare l'API per tutti i tuoi prodotti contemporaneamente. Sebbene le modifiche incrementali possano essere inviate man mano che si verificano, distribuisci le richieste di sincronizzazione completa in modo uniforme nel corso della giornata per rispettare le quote di chiamate ai metodi al minuto e giornaliere. Per maggiori dettagli, consulta Quote e limiti e Aggiorna di frequente i tuoi prodotti.

Test dell'integrazione

Convalida la logica di integrazione in un ambiente sicuro prima di passare alla produzione.

Utilizza gli account di prova

Prima di apportare modifiche in produzione, ti consigliamo di eseguire i passaggi iniziali della migrazione in un account di test in sandbox:

  1. Crea un account di prova: configura un account di prova isolato per fare esperimenti in sicurezza senza influire sugli annunci pubblicati o sulle schede senza costi.
  2. Crea un'origine dati API: esercitati a creare l'origine dati principale dell'API.
  3. Testa le regole degli attributi: verifica le trasformazioni dei dati e le unioni dei feed supplementari.
  4. Convalida i payload e i codici prodotto: invia prodotti di esempio per verificare l'uso di maiuscole e minuscole, la codifica e la gestione degli errori degli SKU.

Per maggiori dettagli, consulta Passaggio 1: crea account di test e la guida Account di test.

Convalida l'allineamento del codice prodotto

Assicurati che il codice prodotto del payload programmatico corrisponda esattamente agli SKU del feed di file. Google identifica i prodotti combinando:

  • offerId (chiamato id nei feed basati su file, sensibile alle maiuscole)
  • contentLanguage (ad esempio en)
  • feedLabel (ad esempio US)

Caratteri speciali e codifica

Se gli ID prodotto contengono caratteri come /, % o ~, utilizza il formato codificato (codifica base64url senza spaziatura interna) nelle chiamate API. Per saperne di più, consulta ProductInput.name.

Controllo della concorrenza

In un'integrazione in tempo reale, gli aggiornamenti possono arrivare in ordine sparso a causa della latenza di rete. Per evitare che gli aggiornamenti meno recenti sovrascrivano i dati più recenti, utilizza il campo versionNumber nella risorsa ProductInput.

Playbook per la migrazione passo passo

Se decidi di spostare alcuni o tutti i tuoi prodotti dai feed dei file all'API Merchant, segui questo playbook per eseguire la transizione dei prodotti senza perdere impressioni o cronologia di pubblicazione.

1. Esegui una prova della migrazione in un account di test

Prima di apportare modifiche in produzione, crea un account di test in sandbox utilizzando il metodo accounts.createTestAccount (consulta la guida Account di test). Gli account di prova forniscono un ambiente isolato in cui le offerte vengono approvate per impostazione predefinita, la verifica del dominio non è richiesta e i dati non vengono mai pubblicati pubblicamente.

Utilizza il tuo account di test per eseguire il mirroring della configurazione di produzione e provare la migrazione end-to-end:

  1. Replica la configurazione del feed dei file: crea un'origine dati principale dei file (e qualsiasi origine dati supplementare) nell'account di prova e carica un campione del file del feed di produzione.
  2. Crea un'origine dati API di test e delle regole: crea un'origine dati principale API e configura le regole degli attributi o le unioni dei feed supplementari richieste.
  3. Testa l'acquisizione della proprietà e l'allineamento delle chiavi: invia richieste productInputs.insert per i prodotti di esempio e verifica che l'origine dati API acquisisca la proprietà degli articoli esistenti senza creare prodotti duplicati.
  4. Verifica aggiornamenti ed eliminazioni: testa gli aggiornamenti parziali con productInputs.patch e le rimozioni con productInputs.delete, quindi ispeziona le risorse risultanti con products.get.

2. Crea origini dati API Products

Prima di eseguire il push dei dati, crea un'origine dati principale di tipo API nel tuo account.

Crea l'origine dati principale dell'API

Per creare un'origine dati che accetta i push dell'API, invia una richiesta POST all'endpoint dataSources. Per maggiori dettagli, consulta Crea un'origine dei dati di prodotto principale.

3. Transizione delle regole degli attributi personalizzati

Le regole degli attributi personalizzate sono associate a origini dati specifiche e non vengono trasferite automaticamente dall'origine dati del file alla nuova origine dati dell'API.

La modalità di transizione delle regole degli attributi dipende dal loro scopo:

  • Unione tra origini e feed supplementari di terze parti: se combini i dati dell'API principale con origini dati supplementari esterne (ad esempio file di fornitori di terze parti, fogli di lavoro dell'inventario o feed delle promozioni), devi ricreare le regole degli attributi nell'interfaccia utente di Merchant Center e collegarle alla nuova origine dati dell'API. La pre-elaborazione lato client non può sostituire le regole che uniscono i dati di più origini indipendenti.
  • Trasformazioni dei dati da un'unica origine: per la pulizia, i valori predefiniti o la formattazione delle stringhe da un'unica origine sui dati del catalogo principale, scegli tra:
    • Trasformazioni di backend (consigliato): applica le trasformazioni nel tuo sistema prima di chiamare l'API. In questo modo, avrai un maggiore controllo programmatico, test più semplici e un debug semplificato.
    • Regole degli attributi di Merchant Center: ricrea le regole di trasformazione per la nuova origine dati API nell'interfaccia utente di Merchant Center se vuoi che Merchant Center continui a gestirle automaticamente.

4. Attiva l'integrazione dell'API

Attiva l'integrazione dell'API Products per iniziare a inserire, aggiornare ed eliminare i prodotti nella nuova origine dati principale dell'API:

  • Inserisci e aggiorna i prodotti (acquisizione della proprietà): invia richieste productInputs.insert e productInputs.patch dalla tua integrazione. Quando inserisci un prodotto utilizzando l'API con la stessa chiave (offerId, contentLanguage, feedLabel) di un prodotto esistente nel feed basato su file, l'origine dati dell'API acquisisce la proprietà del prodotto e ne conserva la cronologia di pubblicazione. Per ulteriori indicazioni, consulta Inserisci un prodotto e Aggiungi e gestisci i prodotti.

  • Elimina i prodotti non più disponibili: configura l'integrazione in modo che chiami esplicitamente productInputs.delete ogni volta che un prodotto viene rimosso dal catalogo.

  • Esegui il deployment gradualmente: per i cataloghi di grandi dimensioni, attiva l'integrazione un subaccount Merchant Center o un'origine dati alla volta.

  • Configura la contemporaneità: se invii molte richieste, configura il client per gestire le richieste in parallelo e più connessioni. Consulta la guida Rifattorizza il codice per le richieste in parallelo.

5. Metti in pausa gli aggiornamenti dell'origine dati del file

Una volta attivata l'integrazione dell'API, interrompi gli aggiornamenti dei file prima della successiva esecuzione pianificata del file, in modo che l'origine dati del file non sovrascriva gli aggiornamenti dell'API:

  1. Interrompi il caricamento di nuovi file nella posizione SFTP/FTP, in Google Cloud Storage o in Fogli Google.
  2. Nell'interfaccia utente di Merchant Center, vai all'origine dati del file e metti in pausa il recupero programmato.
  3. I prodotti esistenti di proprietà dell'origine dati del file rimangono pubblicati per un massimo di 30 giorni, finché non vengono inseriti dall'integrazione dell'API.

6. Attendi il completamento della migrazione e verifica

Attendi che tutti i prodotti attivi vengano migrati dall'origine dati file all'origine dati API. Mentre gli aggiornamenti incrementali eseguono la migrazione dei prodotti man mano che cambiano, l'esecuzione di una sincronizzazione completa del catalogo a ritmo regolare tramite l'integrazione standard accelera la migrazione dell'intero catalogo (consulta Strategia di sincronizzazione e quote).

Durante questa fase:

  1. Nella UI di Merchant Center, monitora il numero di articoli. Attendi che il conteggio dell'origine dati del file scenda a 0 e che il conteggio dell'origine dati dell'API corrisponda al tuo catalogo attivo.
  2. Utilizza products.get per verificare che gli attributi e le regole degli attributi personalizzati vengano uniti come previsto.
  3. Monitora lo strumento Diagnostica API nell'interfaccia utente di Merchant Center per monitorare le percentuali di errore e le prestazioni dell'API.

7. Dismettere l'origine dati del file

Una volta completata la transizione e quando il numero di elementi del feed dei file è 0:

  1. Verifica che gli aggiornamenti vengano applicati in tempo reale.
  2. Elimina l'origine dati dei file legacy nell'interfaccia utente di Merchant Center per evitare che gli aggiornamenti basati su file sovrascrivano accidentalmente i dati dell'API.
Indietro
Migrate Local Inventory Ads settings