商品资源调用

欢迎推出 Merchant API 的 Beta 版。这是 Content API for Shopping 及未来。

有关 Merchant API 如何改进您的集成以及如何帮助塑造 请参阅发布 Merchant API Beta 版。

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
标题	黑色 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	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 天以上的商品 自动删除

显示的示例插入了新的“黑色 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.update 仅要求您 指定要更改的字段。

注意 ：更新商品的行为与 products.insert 类似，最多花费 处理更改所需的时间如果 products.update 在没有 则更新成功。对 products.get 的后续调用可能会返回 更新之前的值，直至更新处理完毕。

警告 ：如果商品已经处理完毕，则通过 product.update 所做的更改不会保留。 产品 ID 相同的产品。 或 API。如果您希望在重新提交后保持不变，请确保更新 值包含在 Feed 中，或通过 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

如需删除单件商品，请使用 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"
   ]
  }
 ]
}