此页面由 Cloud Translation API 翻译。

商品资源调用

products 资源可以帮助您灵活管理 60 多个商品属性。有一些字段是必填字段，如果缺少这些字段，商品将不能获准在 Google 购物上展示。有许多可选字段可能会根据不同的条件（例如地理位置、商品类型、商品款式/规格和商品套装）变为必填字段。如需详细了解可为商品配置的 60 多个可选参数，请参阅商品数据规范。

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

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 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 美元
库存状况	有货	有货	有货
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	00638NIC	00638ANG	00638ABC
brand	Google	Google	Google
Google 商品类别	服饰与配饰 > 服装	服饰与配饰 > 服装	服饰与配饰 > 服装配饰 > 帽子
颜色	黑色	绿色	黑色
size	L	M	M
age_group	成人内容	成人内容	成人内容
gender	男性	男性	男女皆宜
included_destination	Shopping Actions、购物广告	Shopping Actions、购物广告	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 自定义属性会将每个客户订单的购买上限设置为商品定义，并且 Feed 也支持该属性。该属性目前处于测试阶段，直到获得 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.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 会列出商家在商家中心数据库中拥有的所有商品。请使用以下请求网址：

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"
   ]
  }
 ]
}

产品 ID

批处理模式