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/ |
https://shop.example.com/ |
https://shop.example.com/ |
'gtin' [GTIN] | 9504000059422 | 9504000059446 | 9504000059452 |
'mpn' [MPN] | 00638NIC | 00638ANG | 00638ABC |
品牌 [brand] | |||
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"
]
}
]
}