chiamate a risorse di prodotti

La risorsa products offre molta flessibilità e controllo su più di 60 attributi di prodotto.Esistono diversi campi obbligatori che devono essere inclusi per ottenere l'approvazione per la visualizzazione su Google Shopping. Esistono una serie di campi facoltativi che possono diventare obbligatori in base a condizioni diverse, come 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 ti consente di insert, get, update e delete un prodotto alla volta e di 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 su quali potrebbero essere.

Nei nostri esempi di API, utilizziamo tre prodotti: due t-shirt Google e un berretto Google. Utilizziamo un insieme minimo di dati di prodotto mostrati nella tabella di seguito per effettuare products chiamate alla risorsa per inserire, ricevere, 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 la sezione ID prodotto.

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
title	La maglietta nera Google	Maglietta verde Google	Cappello twill di Google
descrizione	La maglietta nera Google	T-shirt Google 100% cotone	Cappello Google classico
ID gruppo di articoli	google_tee	google_tee
collegare	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
Condizione	Novità	Novità	Novità
price	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
[gtin]	9504000059422	9504000059446	9504000059452
mpn	00638NIC	00638ANG	ABC
brand	Google	Google	Google
Categoria di prodotto Google	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Accessori di abbigliamento > Cappelli
colore	nero	green	nero
dimensioni	L	L	L
age_group	contenuti erotici	contenuti erotici	contenuti erotici
genere	uomo	uomo	unisex
included_destination	Shopping Actions, annunci Shopping	Shopping Actions, annunci Shopping	Shopping Actions

products.insert

Per inserire un singolo prodotto, usa il seguente URL di 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 precedenti chiamate API per il prodotto in questione.

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

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"
 ]
}

Un prodotto può anche avere attributi personalizzati impostati all'interno del corpo JSON. Ad esempio, possiamo impostare un valore 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 ordine del cliente alla definizione di prodotto ed è supportato anche dai feed. L'attributo è attualmente in versione beta fino a quando non sarà completamente supportato dall'API. Qualsiasi attributo personalizzato aggiuntivo può essere aggiunto da un commerciante, ma non comporta un'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 i campi id, offerId, contentLanguage, feedLabel e channel:

{
 "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 un prodotto appena inserito sia disponibile tramite questa chiamata.

Utilizza i seguenti parametri e URL di richiesta HTTP, il tuo ID commerciante e l'ID prodotto (formato ID REST) relativo al prodotto che vuoi ricevere:

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

Una chiamata riuscita restituisce un HTTP 200 e la "risorsa di 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 di fornire tutti i campi applicabili, products.update richiede solo di specificare i campi da 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 ha esito positivo senza error, l'aggiornamento ha esito positivo. Le seguenti chiamate a products.get potrebbero restituire il valore precedente fino all'elaborazione dell'aggiornamento.

Avviso: le modifiche apportate con product.update non vengono mantenute se il prodotto con lo stesso ID prodotto viene reinviato tramite il feed principale, il feed supplementare o l'API. Se vuoi che un valore rimanga invariato dopo il reinvio, 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 aggiorna i valori title e description di una "T-shirt Google nera" esistente con i dati di prodotto forniti nel corpo della richiesta, lasciando tutti gli altri campi invariati.

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 tutti gli altri campi invariati.

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 della stringa di query deve essere un elenco separato da virgole di campi da modificare. updateMask è utile quando vuoi dichiarare che verranno aggiornati solo i campi denominati. Non specificare un updateMask equivale a contrassegnare tutti i campi della richiesta da aggiornare, come mostrato nell'esempio precedente.

L'esempio mostrato aggiornerà solo i valori 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 specificato nell'elenco updateMask, ma non nel corpo della richiesta, verrà eliminato dalla risorsa Product, se esistente.

L'esempio mostrato utilizzerà updateMask per rimuovere il valore per il campo salePrice.

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

Il corpo della richiesta di esempio non deve includere il campo salePrice per eliminarlo. Puoi anche non fornire alcun 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, l'eliminazione del campo equivale a quella del campo.

Per utilizzare updateMask in una richiesta products.custombatch, è necessario specificare updateMask nel corpo della richiesta.

L'esempio mostrato aggiornerà 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) relativo al 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 presenti nel database di Merchant Center. Usa il seguente URL di richiesta:

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

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

Vengono restituiti i seguenti tre prodotti di esempio:

{
 "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"
   ]
  }
 ]
}