Tài nguyên products
mang lại rất nhiều tính linh hoạt và giúp bạn có nhiều quyền kiểm soát hơn đối với hơn 60 thuộc tính sản phẩm.Có một số trường là bắt buộc và bạn phải đưa vào để được phê duyệt hiển thị trên Google Mua sắm.
Có một số trường không bắt buộc có thể trở thành trường bắt buộc dựa trên nhiều điều kiện như vị trí, loại sản phẩm, các biến thể sản phẩm và gói sản phẩm. Để biết thêm thông tin chi tiết về hơn 60 thông số không bắt buộc có thể được định cấu hình cho sản phẩm, hãy tham khảo Thông số kỹ thuật dữ liệu sản phẩm.
Tài nguyên products
cho phép bạn insert
, get
, update
và delete
từng sản phẩm một và list
tất cả sản phẩm trong cơ sở dữ liệu của Merchant Center.
Bạn có thể dùng tài nguyên productstatuses
để kiểm tra trạng thái phê duyệt hoặc từ chối của một sản phẩm cụ thể cho một đích đến. Hãy tham khảo hướng dẫn về trạng thái sản phẩm để biết thêm chi tiết về những sản phẩm có thể có vấn đề về chất lượng dữ liệu và các vấn đề có thể xảy ra.
Trong các ví dụ về API, chúng tôi sử dụng 3 sản phẩm: 2 áo thun Google và mũ Google. Chúng tôi sử dụng một tập dữ liệu sản phẩm tối thiểu hiển thị trong bảng bên dưới để thực hiện các lệnh gọi tài nguyên products
để chèn, tải, cập nhật, liệt kê và xoá từng sản phẩm cũng như lô sản phẩm.
Bạn nên định cấu hình Thông tin vận chuyển và thuế ở cấp tài khoản thay vì ở cấp sản phẩm.
Đối với tài khoản phụ nhiều người bán của Trang web thương mại, tất cả sản phẩm phải bao gồm trường external_seller_id
. Hãy xem bài viết Mã sản phẩm để biết thêm chi tiết.
id | online:en:US:1111111111 | online:en:US:2222222222 | online:en:US:3333333333 |
---|---|---|---|
offerId | 1111111111 | 2222222222 | 3333333333 |
title | Áo phông Google màu đen | Áo phông Google màu xanh lục | Mũ lưỡi trai Google |
description | Áo phông Google màu đen | Áo thun Google 100% cotton | Mũ Google cổ điển |
mã nhóm mặt hàng | google_tee | google_tee | |
liên kết | http://my.site.com/blacktee | http://my.site.com/greentee | http://my.site.com/blackhat |
điều kiện | Mới | Mới | Mới |
price | 219900.00 VND | 219900.00 VND | 109.900 VND |
độ khả dụng | Còn hàng | Còn hàng | Còn hàng |
imageLink | https://shop.example.com/ |
https://shop.example.com/ |
https://shop.example.com/ |
gtin (mã số sản phẩm thương mại toàn cầu) | 9504000059422 | 9504000059446 | 9504000059452 |
mpn (mã số linh kiện của nhà sản xuất) | 00638NIC | 00638ANG | 00638ABC |
brand | |||
Danh mục sản phẩm của Google | Quần áo & Phụ kiện > Quần áo | Quần áo & Phụ kiện > Quần áo | Quần áo & Phụ kiện > Phụ kiện quần áo > Mũ |
màu | đen | xanh lục | đen |
size | L | M | M |
age_group | người lớn | người lớn | người lớn |
gender | nam | nam | trung tính |
included_destination | Mua sắm Trực tiếp, Quảng cáo mua sắm | Mua sắm Trực tiếp, Quảng cáo mua sắm | Shopping Actions |
products.insert
Để chèn một sản phẩm, hãy sử dụng URL yêu cầu sau đây, trong đó chỉ định mã người bán của bạn và nội dung JSON mẫu. Phụ trang tạo ra sản phẩm mới. Nếu các giá trị tồn tại cho các thuộc tính channel
, contentLanguage
, offerId
và feedLabel
của một sản phẩm nhất định, thì phương thức này sẽ cập nhật mục nhập đó và thay thế tất cả dữ liệu từ các lệnh gọi API trước đó cho sản phẩm nhất định.
Những sản phẩm bị loại trừ khỏi mọi vị trí xuất hiện trong hơn 7 ngày sẽ tự động bị xoá.
Ví dụ minh hoạ sẽ chèn một "Áo thun Google đen" mới cho các sản phẩm hiện có.
POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products
Lệnh gọi nội dung yêu cầu mẫu cho 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"
]
}
Một sản phẩm cũng có thể có các thuộc tính tuỳ chỉnh được đặt trong phần nội dung JSON. Ví dụ: chúng tôi có thể đặt purchase_quantity_limit
cho một sản phẩm duy nhất để giới hạn số lượng mặt hàng mà khách hàng có thể đặt hàng:
"customAttributes": [
{
"name": "purchase_quantity_limit",
"value": "4"
}
]
Xin lưu ý rằng thuộc tính tuỳ chỉnh purchase_quantity_limit
đặt giới hạn mua hàng cho mỗi đơn đặt hàng của khách hàng thành định nghĩa sản phẩm và cũng được nguồn cấp dữ liệu hỗ trợ. Thuộc tính này hiện đang ở giai đoạn thử nghiệm cho đến khi được API hỗ trợ đầy đủ. Người bán có thể thêm bất kỳ thuộc tính tuỳ chỉnh bổ sung nào nhưng không dẫn đến bất kỳ quá trình xử lý cụ thể nào của API.
Lệnh gọi thành công sẽ trả về một mã HTTP 200
và nội dung phản hồi chứa tài nguyên sản phẩm đã chèn chỉ có id
, offerId
, contentLanguage
, feedLabel
và channel
được điền sẵn:
{
"kind": "content#product",
"id": "online:en:US:1111111111",
"offerId": "1111111111",
"contentLanguage": "en",
"targetCountry": "US",
"feedLabel": "US",
"channel": "online"
}
products.get
Để nhận thông tin về một sản phẩm cụ thể trong cơ sở dữ liệu của Merchant Center, hãy sử dụng products.get
. Có thể mất vài phút để một sản phẩm mới được chèn
xuất hiện thông qua lệnh gọi này.
Sử dụng các tham số và URL yêu cầu HTTP sau, mã người bán và mã sản phẩm (định dạng mã REST) cho sản phẩm mà bạn muốn tải:
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
Lệnh gọi thành công sẽ trả về một HTTP 200
và "tài nguyên sản phẩm" trong nội dung phản hồi. Dưới đây là dữ liệu sản phẩm mẫu được truy xuất từ một sản phẩm có mã 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
Để cập nhật một sản phẩm, hãy sử dụng URL yêu cầu sau với phương thức PATCH, trong đó chỉ định mã người bán, mã sản phẩm và nội dung JSON chứa dữ liệu mà bạn muốn cập nhật cho sản phẩm. Không giống như products.insert
, yêu cầu bạn cung cấp mọi trường có thể áp dụng, products.update
chỉ yêu cầu bạn chỉ định các trường mà bạn muốn thay đổi.
Để thêm hoặc sửa đổi một thuộc tính, hãy chỉ định trường bằng giá trị mới trong nội dung JSON. Ví dụ dưới đây sẽ cập nhật title
và description
của "Áo thun Google đen" hiện có bằng dữ liệu sản phẩm được cung cấp trong nội dung yêu cầu, giữ nguyên tất cả các trường khác.
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
Lệnh gọi nội dung yêu cầu mẫu cho products.update
:
{
"title": "Google Tee Black Limited Edition",
"description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}
Bạn chỉ có thể cập nhật các trường cấp cao nhất thông qua yêu cầu products.update
.
Nếu muốn cập nhật các trường lồng nhau, bạn phải cung cấp toàn bộ đối tượng cấp cao nhất.
Ví dụ hiển thị sẽ cập nhật đối tượng salePrice
cấp cao nhất, bao gồm cả các trường lồng nhau của sản phẩm hiện có, với dữ liệu sản phẩm được cung cấp trong nội dung yêu cầu, giữ nguyên tất cả các trường khác.
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
{
"salePrice": {
"value": "17.99",
"currency": "USD"
}
}
Để chọn một số trường nhất định cần cập nhật mà không làm thay đổi các trường khác có trong phần nội dung của yêu cầu, bạn có thể chỉ định updateMask
. Tham số chuỗi truy vấn này phải là một danh sách các trường được phân tách bằng dấu phẩy mà bạn muốn sửa đổi.
updateMask
rất hữu ích khi bạn muốn xác nhận rằng chỉ các trường đã đặt tên mới được cập nhật. Việc không chỉ định updateMask
cũng tương đương với việc đánh dấu tất cả các trường trong yêu cầu cập nhật như minh hoạ trong ví dụ trên.
Ví dụ dưới đây sẽ chỉ cập nhật description
và availability
của "Áo phông đen Google" hiện có với dữ liệu sản phẩm tương ứng được cung cấp trong nội dung yêu cầu, để nguyên tất cả các trường khác bao gồm cả title
.
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability
Lệnh gọi nội dung yêu cầu mẫu cho products.update
:
{
"title": "Google Tee Black",
"description": "This Limited Edition is out of print.",
"availability": "out of stock"
}
Nếu một trường được cung cấp trong danh sách updateMask
nhưng không có trong phần nội dung của yêu cầu, thì trường đó sẽ bị xoá khỏi tài nguyên Product
nếu tồn tại.
Ví dụ minh hoạ sẽ sử dụng updateMask
để xoá giá trị của trường salePrice
.
PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice
Nội dung yêu cầu mẫu không được chứa trường salePrice
để xoá trường đó. Bạn cũng có thể không cung cấp hình ảnh hoặc hình ảnh trống. Các trường khác sẽ không bị ảnh hưởng, miễn là không xuất hiện trong updateMask
.
Để sử dụng updateMask
trong một yêu cầu products.custombatch
, bạn phải chỉ định updateMask
trong phần nội dung của yêu cầu.
Ví dụ dưới đây sẽ cập nhật price
và availability
của "Áo phông Google đen" hiện có bằng cách sử dụng products.custombatch
với dữ liệu sản phẩm được cung cấp trong mục nhập lô, giữ nguyên tất cả các trường khác, bao gồm cả title
và 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
Để xoá một sản phẩm, hãy sử dụng products.delete
với URL yêu cầu HTTP mẫu, mã người bán và mã sản phẩm (ở định dạng mã REST, chẳng hạn như online:en:US:1111111111
) cho sản phẩm mà bạn muốn xoá:
DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
Khi phản hồi thành công, hệ thống sẽ trả về một HTTP Status 204
không có nội dung phản hồi.
products.list
products.list
liệt kê mọi sản phẩm mà người bán có trong cơ sở dữ liệu của Merchant Center. Sử dụng URL yêu cầu sau:
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products
Lệnh gọi thành công sẽ trả về dữ liệu HTTP 200
và JSON cho các sản phẩm trong khoá "resource".
Ba sản phẩm ví dụ sau đây được trả về:
{
"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"
]
}
]
}