products
資源提供極大彈性,可讓您進一步控管 60 種以上的產品屬性。許多必填欄位都必須加入,才能獲準顯示在 Google 購物中。根據地點、產品類型、產品子類和產品組合等不同條件,可能提供多個選填欄位。如要進一步瞭解可為產品設定的 60 多種選用參數,請參閱產品資料規格。
透過 products
資源,您可以一次 insert
、get
、update
和 delete
一項產品,list
則可提供 Merchant Center 資料庫中的所有產品。
productstatuses
資源可用於查看特定目的地中特定產品的核准狀態。請參閱產品狀態指南,進一步瞭解哪些產品可能有資料品質問題,以及可能的問題。
在我們的 API 範例中,我們使用三項產品:兩組 Google T 恤和 Google 上限。我們會使用下表中的最少產品資料,讓 products
資源呼叫用於插入、取得、更新、列出及刪除個別產品和批次產品。
我們建議在帳戶層級設定運送與稅務資訊,而不要在產品層級設定。
如為 Marketplaces 的多重賣方子帳戶,所有產品都必須包含 external_seller_id
欄位。詳情請參閱產品 ID。
ID | online:en:US:1111111111 | online:en:US:2222222222 | online:en:US:3333333333 |
---|---|---|---|
offerId | 1111111111 | 2222222222 | 3333333333 |
title | Google 黑色 T 恤 | Google T 恤 | Google 廣告上限 |
description | Google 黑色 T 恤 | 100% 純 Google T 恤 | 經典 Google 帽子 |
商品群組 ID | google_tee | google_tee | |
連結 | http://my.site.com/blacktee | http://my.site.com/greentee | http://my.site.com/blackhat |
條件 | 新品 | 新品 | 新品 |
價格 | $21.99 美元 | $21.99 美元 | $10.99 美元 |
availability (供應情形) | 有現貨 | 有現貨 | 有現貨 |
imageLink | https://shop.example.com/ |
https://shop.example.com/ |
https://shop.example.com/ |
全球交易品項識別碼 | 9504000059422 | 9504000059446 | 9504000059452 |
製造商零件編號 | 00638NIC | 00638ANG | 00638ABC |
brand | |||
Google 產品類別 | 服飾與配件 > 衣著 | 服飾與配件 > 衣著 | 服飾與配件 > 服飾配件 > 帽子 |
顏色 | 霧黑 | green | 霧黑 |
大小 | L | M | M |
age_group | 成人 | 成人 | 成人 |
gender | 男性 | 男性 | 男女通用 |
included_destination | Shopping Actions、購物廣告 | Shopping Actions、購物廣告 | Shopping Actions |
products.insert
如要插入單一產品,請使用下列要求網址,指定您的商家 ID 和範例 JSON 主體。插入內容時,系統會建立新的產品。如果特定產品的 channel
、contentLanguage
、offerId
和 feedLabel
屬性有值,這個方法會更新該項目,並取代先前 API 呼叫中該產品的所有資料。
系統會自動刪除從所有目的地排除超過 7 天的產品。
畫面上的示例會在現有產品中插入新的「黑色 Google Te」。
POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products
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"
]
}
產品也可以在 JSON 主體中設定自訂屬性。舉例來說,我們可以為單一產品設定 purchase_quantity_limit
,藉此限制客戶可訂購的商品數量:
"customAttributes": [
{
"name": "purchase_quantity_limit",
"value": "4"
}
]
請注意,purchase_quantity_limit
自訂屬性會根據產品定義為每位客戶設定的購買數量限制,而動態饋給也支援這個方式。屬性目前仍在 Beta 版測試階段,直到 API 完全支援為止。商家可以新增任何額外的自訂屬性,但不會讓 API 進行任何特定處理。
如果呼叫成功,會傳回 HTTP 200
代碼和回應主體,其中包含插入的產品資源,且只填入 id
、offerId
、contentLanguage
、feedLabel
和 channel
:
{
"kind": "content#product",
"id": "online:en:US:1111111111",
"offerId": "1111111111",
"contentLanguage": "en",
"targetCountry": "US",
"feedLabel": "US",
"channel": "online"
}
products.get
如要取得 Merchant Center 資料庫中特定產品的資訊,請使用 products.get
。新插入的產品可能需要幾分鐘的時間,才能透過這個呼叫使用。
針對您想要取得的產品,使用下列 HTTP 要求網址和參數、您的商家 ID,以及產品 ID (REST ID 格式):
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
如果呼叫成功,會在回應主體中傳回 HTTP 200
和「產品資源」。以下是從 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
如要更新單一產品,請搭配 PATCH 方法使用以下要求網址,並指定您的商家 ID、產品 ID 和含有您要為產品更新的資料的 JSON 主體。與 products.insert
不同的是,必須提供所有適用欄位。products.update
只是要求您指定要變更的欄位。
如要新增或修改屬性,請在 JSON 主體中指定含有新值的欄位。顯示的範例會根據要求主體中提供的產品資料更新現有「黑色 Google Te」的 title
和 description
,讓所有其他欄位維持不變。
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
products.update
的要求主體呼叫範例:
{
"title": "Google Tee Black Limited Edition",
"description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}
只有透過 products.update
要求可以更新頂層欄位。如要更新巢狀欄位,您必須提供整個頂層物件。
顯示的範例會更新頂層 salePrice
物件,包括現有產品的巢狀欄位,其中包含要求主體中提供的產品資料,讓所有其他欄位維持不變。
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
{
"salePrice": {
"value": "17.99",
"currency": "USD"
}
}
如要選取要更新的特定欄位,而不變更要求主體中的其他欄位,您可以指定 updateMask
。這個查詢字串參數應為您要修改的欄位清單,並以半形逗號分隔。如要宣告只有已命名欄位會更新,updateMask
就很實用。不指定 updateMask
,等同於將要求中的所有欄位標示為待更新,如上例所示。
畫面上的範例只會更新現有「黑色 Google Te」的 description
和 availability
,並提供要求主體中提供的對應產品資料,讓所有其他欄位 (包括 title
) 維持不變。
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability
products.update
的要求主體呼叫範例:
{
"title": "Google Tee Black",
"description": "This Limited Edition is out of print.",
"availability": "out of stock"
}
如果 updateMask
清單中提供某個欄位,但要求主體未提供該欄位,系統會從 Product
資源 (如有) 刪除該欄位。
顯示的範例會使用 updateMask
移除 salePrice
欄位的值。
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice
要求主體範例不應包含 salePrice
欄位才能刪除。請勿提供內文或空白內文。如果其他欄位未顯示在 updateMask
中,其他欄位不會受到影響。
如要在 products.custombatch
要求中使用 updateMask
,必須在要求主體中指定 updateMask
。
這個範例會使用 products.custombatch
搭配批次項目提供的產品資料,更新現有「黑色 Google Te」的 price
和 availability
,讓所有其他欄位 (包括 title
和 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
如要刪除單一產品,請為要刪除的產品使用 products.delete
,搭配範例 HTTP 要求網址、商家 ID 和產品 ID (採用 REST ID 格式,例如 online:en:US:1111111111
):
DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
成功的回應會傳回沒有回應主體的 HTTP Status 204
。
products.list
products.list
會列出商家在 Merchant Center 資料庫中的所有產品。請使用以下要求網址:
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products
如果呼叫成功,系統會傳回「resources」鍵中產品的 HTTP 200
和 JSON 資料。
系統會傳回以下三個產品範例:
{
"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"
]
}
]
}