本頁面由 Cloud Translation API 翻譯而成。

產品資源呼叫

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/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
全球交易品項識別碼	9504000059422	9504000059446	9504000059452
製造商零件編號	00638NIC	00638ANG	00638ABC
brand	Google	Google	Google
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"
   ]
  }
 ]
}

商品 ID

批次模式