此页面由 Cloud Translation API 翻译。

商品资源调用

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
标题	黑色 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	新观看者	新观看者	新观看者
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
'gtin' [GTIN]	9504000059422	9504000059446	9504000059452
'mpn' [MPN]	00638NIC	00638ANG	00638ABC
品牌 [brand]	Google	Google	Google
Google 商品类别	服饰与配饰 > 服装	服饰与配饰 > 服装	服饰与配饰 > 服装配饰 > 帽子
颜色	黑色	绿色	黑色
大小	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 使用批处理条目中提供的商品数据更新现有“Black 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

成功的调用将返回“资源”键中商品的 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"
   ]
  }
 ]
}