商品资源调用

products 资源提供了极大的灵活性和 60 多个商品属性控制能力。有一些字段是必填字段，必须也包含在内才能获批在 Google 购物上展示。根据位置、商品类型、商品款式/规格和商品套装等不同条件，有一些可选字段可能变为必填字段。如需详细了解可以为商品配置的 60 多个可选参数，请参阅商品数据规范。

借助 products 资源，您可以一次对一个商品执行 insert、get、update 和 delete 操作，并对 Merchant Center 数据库中的所有商品执行 list 操作。

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 斜纹帽
说明 黑色 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
condition 新 新 新
价格 21.99 美元 21.99 美元 10.99 美元
库存状况 有货 有货 有货
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
'gtin' [GTIN] 9504000059422 9504000059446 9504000059452
'mpn' [MPN] 00638NIC 00638ANG 00638ABC
品牌 [brand] Google Google Google
Google 商品类别 服饰与配饰 > 服装 服饰与配饰 > 服装 服饰与配饰 > 服装配饰 > 帽子
颜色 黑色 green 黑色
大小 L M M
age_group 成人内容 成人内容 成人内容
gender 男性 男性 男女皆宜
included_destination 购物行动计划、购物广告 购物行动计划、购物广告 购物行动

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 自定义属性将每个客户订单的购买限额设置为商品定义，并且 Feed 也支持该属性。该属性目前处于 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 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。

所显示的示例将使用 products.custombatch 与批处理条目中提供的商品数据更新现有“黑色 Google T 恤”的 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"
   ]
  }
 ]
}