chiamate a risorse di prodotti

La risorsa products offre un elevato livello di flessibilità e controllo su oltre 60 attributi dei prodotti.Esistono diversi campi obbligatori, che devono essere inclusi per l'approvazione della visualizzazione su Google Shopping. Esistono diversi campi facoltativi che possono diventare obbligatori in base a varie condizioni, come località, tipo di prodotto, varianti di prodotto e bundle 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 mancata approvazione di un prodotto specifico per una destinazione. Per ulteriori dettagli sui product status guide che potrebbero presentare problemi di qualità dei dati e su quali potrebbero essere questi problemi, consulta la guida sullo stato dei prodotti.

Nei nostri esempi di API, utilizziamo tre prodotti: due t-shirt Google e un cappellino Google. Utilizziamo un set minimo di dati di prodotto mostrati nella tabella riportata di seguito per effettuare chiamate alla risorsa products per inserire, recuperare, aggiornare, elencare ed eliminare singoli prodotti e batch di prodotti.

Ti consigliamo di configurare le informazioni su spedizione e imposte a livello di account anziché a livello di prodotto.

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

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
titolo	The Black Google Tee	Google Tee Green	Google Twill Cap
descrizione	The Black Google Tee	T-shirt Google in 100% cotone	Cappellino Google classico
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 USD	21,99 USD	10,99 USD
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 [gtin]	9504000059422	9504000059446	9504000059452
mpn	00638NIC	00638ANG	00638ABC
brand [marca]	Google	Google	Google
Categoria di prodotto Google	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Abbigliamento	Abbigliamento e accessori > Accessori per l'abbigliamento > Cappelli
colore	nero	verde	nero
dimensioni	L	M	M
age_group	adult	adult	adult
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 l'ID commerciante e un corpo JSON di esempio. Un'inserzione crea il nuovo prodotto. Se esistono valori per gli attributi channel, contentLanguage, offerId e feedLabel per 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 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 nel corpo JSON. Ad esempio, possiamo impostare un purchase_quantity_limit per un singolo prodotto per 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 cliente nella definizione del prodotto ed è supportato anche dai feed. L'attributo è attualmente in versione beta fino a quando non sarà completamente supportato dall'API. Un commerciante può aggiungere qualsiasi attributo personalizzato aggiuntivo, 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 del 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 un prodotto appena inserito sia disponibile tramite questa chiamata.

Utilizza il seguente URL e i seguenti parametri della richiesta HTTP, l'ID commerciante e l'ID prodotto (formato ID REST) per il prodotto che vuoi recuperare:

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

Una chiamata riuscita restituisce un codice HTTP 200 e la "risorsa del prodotto" nel corpo della risposta. Ecco i 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 della 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.

Per aggiungere o modificare un attributo, specifica il campo con il nuovo valore nel corpo JSON. L'esempio mostrato aggiornerà title e description di una "T-shirt Google nera" 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}

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 request. 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 della stringa di query deve essere un elenco di campi separati da virgole che vuoi modificare. Un updateMask è utile quando vuoi assicurarti che vengano aggiornati solo i campi denominati. Se non specifichi un updateMask, è come se avessi contrassegnato tutti i campi della richiesta da aggiornare, come mostrato nell'esempio precedente.

L'esempio mostrato aggiornerà solo 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 esiste.

L'esempio mostrato utilizzerà updateMask per rimuovere il valore del 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 un corpo o un corpo vuoto. Gli altri campi rimarranno invariati a condizione che non vengano visualizzati in updateMask.

Per utilizzare updateMask all'interno di una richiesta products.custombatch, updateMask deve essere specificato 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, inclusi 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, l'ID commerciante e l'ID prodotto (in formato ID REST, ad esempio online:en:US:1111111111) per il prodotto che vuoi eliminare:

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

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

products.list

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

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

Una chiamata riuscita restituisce un codice HTTP 200 e dati 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"
   ]
  }
 ]
}