chiamate a risorse di prodotti

Ti contattiamo per presentare la versione beta dell'API Merchant Center. È la nuova versione dell'API Content e quella futura.

La risorsa products offre una grande flessibilità e un notevole controllo su oltre 60 attributi dei prodotti.Alcuni campi sono obbligatori e devono essere inclusi per poter essere approvati per la visualizzazione su Google Shopping. Esistono diversi campi facoltativi che possono diventare obbligatori in base a diverse condizioni, ad esempio località, tipo di prodotto, varianti di prodotto e set di prodotti. Per ulteriori dettagli sugli oltre 60 parametri facoltativi che possono essere configurati per i prodotti, consulta le Specifiche dei dati di prodotto.

La risorsa products consente di insert, get, update e delete un prodotto alla volta e list tutti i prodotti nel database di Merchant Center.

La risorsa productstatuses può essere utilizzata per verificare lo stato di approvazione o disapprovazione di un prodotto specifico per una destinazione. Consulta la guida allo stato dei prodotti per ulteriori dettagli su quali prodotti potrebbero presentare problemi di qualità dei dati e quali potrebbero essere.

Negli esempi relativi alle nostre API, utilizziamo tre prodotti: due t-shirt Google e un berretto Google. Utilizziamo un insieme minimo di dati di prodotto, mostrato nella tabella seguente, per effettuare products chiamate alle risorse per inserire, ottenere, aggiornare, elencare ed eliminare singoli prodotti e gruppi di prodotti.

Ti consigliamo di configurare i dati fiscali e di spedizione a livello di account anziché a livello di prodotto.

Per i subaccount multi-venditore dei Marketplace, tutti i prodotti devono includere il campo external_seller_id. Per ulteriori dettagli, consulta ID prodotto.

ID	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
qualifica	La T-shirt nera di Google	Maglietta Google verde	Cappello in twill di Google
descrizione	La T-shirt nera di Google	T-shirt Google in cotone 100%	Cappello classico Google
ID gruppo di articoli	google_tee	google_tee
link	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
Condizione	Novità	Novità	Novità
prezzo	21.99 EUR	21.99 EUR	10.99 EUR
disponibilità	Disponibile	Disponibile	Disponibile
imageLink	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
ean	9504000059422	9504000059446	9504000059452
mpn	00638NIC	00638	00638ABC
brand	Google	Google	Google
Categoria di prodotto Google	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Accessori di abbigliamento > Cappelli
color	nero	verde	nero
dimensioni	L	L	L
age_group	contenuti erotici	contenuti erotici	contenuti erotici
gender	uomo	uomo	unisex
included_destination	Shopping Actions, annunci Shopping	Shopping Actions, annunci Shopping	Shopping Actions

products.insert

Per inserire un singolo prodotto, utilizza il seguente URL della richiesta, specificando il tuo ID commerciante e un corpo JSON di esempio. Un inserto crea il nuovo prodotto. Se esistono valori per gli attributi channel, contentLanguage, offerId e feedLabel di un determinato prodotto, questo metodo aggiorna la voce e sostituisce tutti i dati delle chiamate API precedenti per il prodotto in questione.

I prodotti esclusi da tutte le destinazioni per più di 7 giorni vengono automaticamente eliminati.

L'esempio mostrato inserisce una nuova "T-shirt Google nera" nei prodotti disponibili.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Esempio di chiamata del corpo della richiesta per products.insert:

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

Per un prodotto possono essere impostati anche attributi personalizzati nel corpo JSON. Ad esempio, possiamo impostare un purchase_quantity_limit per un singolo prodotto al fine di limitare il numero di articoli che un cliente può ordinare:

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

Tieni presente che l'attributo personalizzato purchase_quantity_limit imposta un limite di acquisto per ogni ordine del cliente alla definizione del prodotto ed è supportato anche dai feed. L'attributo è attualmente in versione beta fino al completamento del supporto dall'API. Qualsiasi altro attributo personalizzato può essere aggiunto da un commerciante, ma non comporta alcuna elaborazione specifica da parte delle API.

Una chiamata riuscita restituisce un codice HTTP 200 e un corpo della risposta contenente la risorsa di prodotto inserita con solo id, offerId, contentLanguage, feedLabel e channel compilati:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

Per ottenere informazioni su un prodotto specifico nel database di Merchant Center, utilizza products.get. Potrebbero essere necessari alcuni minuti prima che il prodotto appena inserito sia disponibile tramite questa chiamata.

Utilizza il seguente URL e i parametri della richiesta HTTP, il tuo ID commerciante e l'ID prodotto (formato ID REST) del prodotto che vuoi ottenere:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Una chiamata riuscita restituisce un HTTP 200 e la "risorsa del prodotto" nel corpo della risposta. Di seguito sono riportati alcuni dati di prodotto di esempio recuperati da un prodotto con ID online:en:US:1111111111:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

Per aggiornare un singolo prodotto, utilizza il seguente URL di richiesta con il metodo PATCH, specificando l'ID commerciante, l'ID prodotto e un corpo JSON contenente i dati che vuoi aggiornare per il prodotto. A differenza di products.insert, che richiede la fornitura di tutti i campi applicabili, products.update richiede solo di specificare i campi che vuoi modificare.

Nota: l'aggiornamento di un prodotto funziona in modo simile a products.insert e richiede alcuni minuti per l'elaborazione delle modifiche. Se products.update riesce senza errori, l'aggiornamento viene eseguito correttamente. Le seguenti chiamate a products.get potrebbero restituire il valore precedente fino a quando l'aggiornamento non è stato elaborato.

Avviso: le modifiche apportate con product.update non vengono mantenute se il prodotto con lo stesso ID prodotto viene inviato nuovamente tramite il feed principale, il feed supplementare o l'API. Se vuoi che un valore venga mantenuto dopo il nuovo invio, assicurati che il valore aggiornato sia incluso nel feed o tramite la chiamata API products.insert.

Per aggiungere o modificare un attributo, specifica il campo con il nuovo valore nel corpo JSON. L'esempio mostrato aggiornerà i title e i description di una "T-shirt Google nera" esistente con i dati di prodotto forniti nel corpo della richiesta, lasciando inalterati tutti gli altri campi.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Esempio di chiamata del corpo della richiesta per products.update:

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

Solo i campi di primo livello possono essere aggiornati tramite una richiesta products.update. Se vuoi aggiornare i campi nidificati, devi fornire l'intero oggetto di primo livello.

L'esempio mostrato aggiornerà l'oggetto salePrice di primo livello, inclusi i campi nidificati di un prodotto esistente, con i dati di prodotto forniti nel corpo della richiesta, lasciando invariati tutti gli altri campi.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

Per selezionare determinati campi da aggiornare senza apportare modifiche agli altri inclusi nel corpo della richiesta, puoi specificare un updateMask. Questo parametro di stringa di query deve essere un elenco separato da virgole di campi da modificare. Un updateMask è utile quando vuoi affermare che verranno aggiornati solo i campi denominati. Non specificare un updateMask è l'equivalente di contrassegnare tutti i campi della richiesta da aggiornare, come mostrato nell'esempio precedente.

L'esempio mostrato aggiornerà solo i description e availability di una "T-shirt Google nera" esistente con i rispettivi dati di prodotto forniti nel corpo della richiesta, lasciando invariati tutti gli altri campi, incluso title.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

Esempio di chiamata del corpo della richiesta per products.update:

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

Se un campo viene fornito nell'elenco updateMask, ma non nel corpo della richiesta, verrà eliminato dalla risorsa Product, se esistente.

Nell'esempio mostrato verrà utilizzato updateMask per rimuovere il valore del campo salePrice.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

Per eliminarlo, il corpo della richiesta di esempio non deve includere il campo salePrice. Puoi anche specificare nessun corpo o un corpo vuoto. Gli altri campi rimarranno invariati a condizione che non vengano visualizzati in updateMask.

Avviso: quando utilizzi updateMask, presta attenzione a fornire il valore corretto per tutti i campi elencati in updateMask. Se non includi il valore nel corpo della richiesta, questo equivale a eliminare il campo.

Per utilizzare updateMask all'interno di una richiesta products.custombatch, updateMask deve essere specificato nel corpo della richiesta.

L'esempio mostrato aggiorna price e availability di una "T-shirt Google nera" esistente utilizzando products.custombatch con i dati di prodotto forniti nella voce batch, lasciando invariati tutti gli altri campi, tra cui title e description.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

Per eliminare un singolo prodotto, utilizza products.delete con l'URL della richiesta HTTP di esempio, il tuo ID commerciante e l'ID prodotto (in formato ID REST come online:en:US:1111111111) del prodotto che vuoi eliminare:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Una risposta corretta restituisce un HTTP Status 204 senza corpo della risposta.

products.list

products.list elenca tutti i prodotti di un commerciante nel database di Merchant Center. Utilizza il seguente URL di richiesta:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Una chiamata riuscita restituisce i dati HTTP 200 e JSON per i prodotti nella chiave "resources".

Vengono restituiti i tre prodotti di esempio seguenti:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}