產品資源呼叫

我們想推出 Beta 版 Merchant API。這是新版本的 Content API for Shopping 與未來發展

如需瞭解 Merchant API 如何改善整合結果，以及如何協助強化整合項目， 未來詳情請參閱 Merchant API Beta 版。

products 這個資源具備極大的彈性 以及高度控管功能 超過 60 個產品屬性 當中有許多必填欄位 這類相片必須經過加入才能顯示在 Google 購物上。 請依據不同因素將幾個選填欄位設為必填欄位 條件，例如地點、產品類型、產品子類和產品 套裝組合。進一步瞭解超過 60 個選用參數 請參閱產品資料 規格。

products 資源可讓您insert、get、update和delete分別 一次產品，以及 list 個 Merchant Center 資料庫中的所有產品。

productstatuses敬上 這項查詢可用於確認 某個目的地的產品請參閱產品狀態 指南，進一步瞭解 產品可能有資料品質問題，且可能出現問題。

在這個 API 範例中，我們使用了三項產品：兩種 Google T 恤和 Google 上限。我們會使用下表中的最少產品資料來完成 發出 products 資源呼叫，藉此插入、取得、更新、列出及刪除 個別產品及一批產品

建議您設定運送與稅務資訊 透過帳戶 level，而不是 以及產品層級

針對以下品牌的多重賣方子帳戶： Marketplace 中的所有產品都必須 包含 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 廣告上限
說明	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 產品類別	服飾與配件 >服飾	服飾與配件 >服飾	服飾與配件 >服飾配件 >帽子
顏色	霧黑	綠色	霧黑
大小	L	M	M
age_group	成人	成人	成人
gender	男性	男性	男女通用
included_destination	Shopping Actions、購物廣告	Shopping Actions、購物廣告	Shopping Actions

products.insert

如要插入單一產品，請使用下列要求網址來指定 商家 ID 和 JSON 內文範例插入內容時，系統會建立新的產品。如果值 屬性有 channel、contentLanguage、offerId 和 這個方法會更新某項產品的 feedLabel，這個方法會更新該項目，並將 來自特定產品之前 API 呼叫的所有資料。

從所有目的地中排除的產品已超過 7 天 自動刪除。

這個範例插入了新的「Black 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 自訂屬性會設定購買限制 每個客戶訂單所對應的產品定義，此外也支援動態饋給。 屬性目前仍在測試階段，直到 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 只要求 指定您要變更的欄位

注意： 更新產品的運作方式與 products.insert 類似，且最多需要 系統就會在幾分鐘內處理變更。如果 products.update 成功，但沒有 錯誤，更新成功。撥打 products.get 的通話可能會回頭 更新處理完成後，先前的值就會保留。

警告： 如果產品處理完成，透過 product.update 所做的變更不會保留 透過主要動態饋給、補充動態饋給，重新提交 ID 相同的產品 或 API如果您希望在重新提交後保留某個值，請務必更新 值包含在動態饋給中，或透過 products.insert API 呼叫。

如要新增或修改屬性，請在 JSON 中指定含有新值的欄位 這個範例會更新現有現有資料的 title 和 description 「黑色 Google T 恤」與要求主體中提供的產品資料不同， 不會變更所有其他欄位

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，相當於將 欄位。

範例只會更新 description 和 availability 現有的「黑色 Google T 恤」中與相對應的產品資料 要求主體，保留所有其他欄位 (包括 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 中，則不會改變。

警告： 使用 updateMask 時，請小心為所有的 欄位，列在 updateMask 中。如未在內文中加入值 就會等同於刪除該欄位。

如要在 products.custombatch 要求中使用 updateMask，請updateMask 必須在要求內文中指定。

這個範例會更新現有現有資料的 price 和 availability 「黑色 Google T 恤」搭配所提供產品資料使用 products.custombatch ，保留其他所有欄位，包括 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

如要刪除單一產品，請搭配 HTTP 要求範例使用 products.delete 網址、商家 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"
   ]
  }
 ]
}