本頁面由 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 Twill Cap
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
條件	新功能	新功能	新功能
price	$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 產品類別	服飾與配件 > 衣著	服飾與配件 > 衣著	服飾與配件 > 衣著配件 > 帽子
顏色	霧黑	綠色	霧黑
size	L	M	M
age_group	成人	成人	成人
gender	男性	男性	男女通用
included_destination	購物行動、購物廣告	購物行動、購物廣告	Shopping Actions

products.insert

如要插入單一產品，請使用下列要求網址，指定您的商家 ID 和 JSON 主體範例。插入插入畫面後，新產品就會變成新產品。如果特定產品的 channel、contentLanguage、offerId 和 feedLabel 屬性值有值，此方法會更新該項目，並取代針對特定產品先前 API 呼叫的所有資料。

如果產品從所有目的地中排除超過 7 天，系統就會自動刪除。

上方範例會在可用產品中插入新的「Black Google T 恤」。

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 主體中的新值指定欄位。顯示的範例會將現有「Black Google Tee」的 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，等同於標示要求中要更新的所有欄位，如上方範例所示。

顯示的範例「只會」更新現有「Black Google Tee」的 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 更新現有「Black Google Tee」的 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

如果呼叫成功，會傳回「資源」鍵中產品的 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

批次模式