Best practice per l'API CSS

Questo documento descrive alcune delle best practice per l'utilizzo dell'API CSS. I suggerimenti forniti in questa pagina non sono obbligatori per utilizzare l'API, ma possono contribuire a chiarire alcuni degli utilizzi previsti.

Configura l'ambiente

Per configurare l'ambiente di sviluppo, segui i passaggi indicati nella documentazione di avvio rapido.

• Genera un file JSON con un utente e le autorizzazioni in Google Cloud Console
• Abilitare l'API CSS in Google Cloud Console
• Aggiungi l'utente con autorizzazioni di amministratore al tuo account CSS (gruppo di CSS o dominio CSS).
• Verifica di utilizzare l'ambito OAuth corretto: https://www.googleapis.com/auth/content

Le librerie client si trovano ora nei repository standard per la maggior parte dei linguaggi di programmazione. Puoi trovare un elenco nella pagina della nostra libreria client.

Utilizzare gli ID corretti

Utilizza gli ID corretti con gli endpoint API corretti:

• API CSS (css.googleapis.com): utilizza l'ID dominio CSS quando interagisci con i prodotti CSS (ad es. accounts/{cssDomainId}/cssProductInputs:insert).
• API Merchant (merchantapi.googleapis.com): utilizza l'API Merchant per i prodotti standard del commerciante.

Se li confondi, si verificheranno errori. Per maggiori dettagli, consulta la panoramica dell'API CSS.

Metodi validi per iniziare

Ti consigliamo di eseguire i test con i seguenti metodi:

ListChildAccounts

ListChildAccounts è una chiamata di sola lettura che elenca tutti i tuoi domini CSS (se chiamata per un gruppo CSS) o i tuoi commercianti (se chiamata per un dominio CSS). Pertanto, è un buon metodo per verificare se tutto è configurato correttamente.

Inserire/elencare/aggiornare/eliminare un prodotto

Una volta verificato che l'API funziona, prova ad aggiungere un prodotto. Assicurati di utilizzare un raw_provided_id che ricordi.

• Inserisci un prodotto di test utilizzando InsertCssProductInput. Abbiamo un codice campione se hai bisogno di aiuto per capire quali attributi inviare.
• Elenca tutti i tuoi prodotti utilizzando ListCssProducts. Prima che un prodotto venga visualizzato dopo l'inserimento, è necessario un breve ritardo di elaborazione, quindi, se non lo vedi, riprova dopo qualche secondo.
• Aggiorna un singolo prodotto utilizzando UpdateCssProductInput utilizzando il tuo cssproductinput.name. Devi inviare solo gli attributi che devono essere aggiornati. Fai riferimento al codice di esempio qui.
• Elimina il prodotto di test utilizzando DeleteCssProductInput. Dovrai utilizzare raw_provided_id.

Utilizzare Async per migliorare le prestazioni

L'API CSS è progettata per le chiamate parallele. Noterai che le prestazioni delle singole operazioni possono essere lente, ma saranno molto più veloci quando chiami la stessa operazione più volte in parallelo. Il modo migliore per utilizzare questa funzionalità è utilizzare la funzionalità asincrona del linguaggio di programmazione.

Esempi di alcuni linguaggi di programmazione:

• Per Java, utilizza insertCssProductInputCallable().futureCall()
• Per Python, utilizza CssProductInputsServiceAsyncClient
• Per C#, utilizza InsertCssProductInputAsync

Trova e utilizza la funzionalità asincrona del tuo linguaggio di programmazione per inserire più prodotti contemporaneamente. Non devi preoccuparti di sovraccaricare i nostri sistemi: a questo servono i limiti di quota.

Per ulteriori dettagli, visita la nostra pagina sulle prestazioni.

Convalidare i payload

Per evitare errori comuni, verifica che i payload JSON siano formattati correttamente:

• Consulta la documentazione ufficiale: fai sempre riferimento all'API CSS di riferimento più recente per definizioni dei campi, enumerazioni, tipi di dati e struttura del payload.
• Esamina i payload di esempio:confronta i tuoi payload con gli esempi di codice forniti per identificare le discrepanze.
• Tipi di dati:assicurati di utilizzare i tipi di dati corretti (ad es. stringhe, oggetti, array) come specificato nella documentazione.
• Test incrementali: inizia con payload validi minimi per confermare la connettività di base e aggiungi gradualmente altri attributi.

Aggiornare un prodotto

Una volta caricato, un prodotto rimane nel nostro sistema finché non viene aggiornato, eliminato o non scade.

• Puoi aggiornare l'intero prodotto inviando di nuovo la richiesta InsertCssProductInput utilizzando lo stesso raw_provided_id che hai utilizzato inizialmente. Per il momento, dovrai inviare i dati di prodotto completi, anche se sono cambiati solo alcuni attributi (magari solo prezzo/disponibilità).
• Puoi aggiornare parti di un prodotto utilizzando il metodo PATCH UpdateCssProductInput, specificando il nome del prodotto e un corpo JSON contenente i dati che vuoi aggiornare per il prodotto. A differenza di InsertCssProductInput, che richiede la compilazione di tutti i campi applicabili, UpdateCssProductInput ti chiede solo di specificare i campi che vuoi modificare.
• Puoi eliminare un prodotto chiamando DeleteCssProductInput con lo stesso raw_provided_id.
• I prodotti scadono automaticamente circa un mese dopo l'ultimo aggiornamento.

Modalità di funzionamento continuo

Una modalità di funzionamento continuo potrebbe avere il seguente aspetto:

• Utilizza i tuoi ID interni come raw_provided_id.
• Carica di nuovo tutti i prodotti a intervalli regolari, ad esempio ogni settimana. In questo modo i prodotti attivi non scadono.
• Aggiorna i singoli prodotti non appena ricevi i dati modificati dai tuoi commercianti.
  • Se non riesci a reagire immediatamente alle modifiche, individua tutti i prodotti modificati di frequente (magari ogni ora) e carica di nuovo solo questi prodotti.
  • Per i prodotti non più disponibili, puoi utilizzare la chiamata di eliminazione o impostare il numero di offerte disponibili su 0.
  • Non inviarci spesso prodotti invariati. Queste chiamate verranno conteggiate ai fini della quota API. È sufficiente un aggiornamento settimanale.

Selezione dell'offerta principale

L'offerta principale non deve necessariamente essere la migliore o la più economica sul tuo sito, ma deve essere messa in evidenza. Puoi utilizzarlo nei casi in cui la tua offerta principale cambia rapidamente: qui puoi selezionare un'altra offerta più stabile.

Controlla di nuovo questo documento di tanto in tanto

Abbiamo ricevuto feedback su come migliorare questa API e stiamo lavorando per rendere disponibili alcuni di questi miglioramenti. Questa pagina verrà aggiornata quando saranno disponibili nuove funzionalità che semplificheranno l'utilizzo dell'API CSS.