產品資源呼叫

products 資源提供極大的彈性，可控管超過 60 項產品屬性。其中有許多必填欄位，必須填寫才能通過核准，在 Google 購物上顯示。視不同條件 (例如地點、產品類型、產品子類和產品組合) 而定，許多選填欄位可能會變成必填欄位。如要進一步瞭解可為產品設定的 60 多個選用參數，請參閱產品資料規格。

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

您可以使用 productstatuses 資源，查看特定產品在特定目的地的核准或拒登狀態。如要進一步瞭解哪些產品可能發生資料品質問題，以及這些問題可能為何，請參閱產品狀態指南。

在我們的 API 範例中，我們使用三項產品：兩件 Google T 恤和一頂 Google 帽子。我們使用下表所示的最低產品資料集，對 products 資源進行呼叫，以插入、取得、更新、列出及刪除個別產品和產品批次。

建議你在帳戶層級設定運送和稅金資訊，而非在產品層級設定。

如果是市集的多賣家子帳戶，所有產品都必須包含 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 Tee Green 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 USD 21.99 USD 10.99 USD
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 男性 男性 unisex
included_destination 購物行動、購物廣告 購物行動、購物廣告 Shopping Actions

products.insert

如要插入單一產品，請使用下列要求網址，並指定商家 ID 和 JSON 主體範例。插入作業會建立新產品。如果特定產品的屬性 channel、contentLanguage、offerId 和 feedLabel 存在值，這個方法會更新該項目，並取代先前 API 呼叫中特定產品的所有資料。

如果使用這個屬性排除產品超過 7 天，系統會自動刪除該產品。

範例顯示的是在可用的產品中插入新的「黑色 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自訂屬性會為每個顧客訂單設定產品定義的購買限制，動態饋給也支援這項屬性。API 完整支援這項屬性前，目前仍為 Beta 版。商家可以新增任何其他自訂屬性，但 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 則需要提供所有適用的欄位。

如要新增或修改屬性，請在 JSON 主體中指定欄位和新值。範例會使用要求主體中提供的產品資料，更新現有「黑色 Google T 恤」的 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 T 恤」的 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。

範例會使用批次項目中提供的產品資料，更新現有「黑色 Google T 恤」的 price 和 availability，並保留所有其他欄位 (包括 title 和 description) 不變。products.custombatch

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 和「resources」鍵中產品的 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
下一頁
批次模式