Khu vực Merchant API là một khu vực địa lý mà bạn có thể dùng làm mục tiêu liên quan đến tài nguyên accounts.products.regionalInventories. Bạn có thể xác định khu vực là tập hợp mã bưu chính hoặc ở một số quốc gia, bằng cách sử dụng tiêu chí nhắm mục tiêu theo địa lý được xác định trước. Để biết thêm thông tin, hãy xem bài viết Thiết lập khu vực.
Merchant API cung cấp các điểm cuối hàng loạt để quản lý khu vực, cho phép bạn tạo, cập nhật và xoá tối đa 100 khu vực trong một lệnh gọi API duy nhất. Đây là lựa chọn lý tưởng cho những người bán quản lý tình trạng còn hàng và giá theo khu vực (RAAP) ở quy mô lớn, giúp cải thiện hiệu quả và đơn giản hoá quy trình tích hợp.
Tổng quan
Batch API cho phép bạn thực hiện những việc sau bằng các phương thức liên kết:
- Tạo nhiều khu vực trong một yêu cầu duy nhất:
regions:batchCreate - Xoá nhiều khu vực cùng lúc:
regions:batchDelete - Cập nhật nhiều khu vực cùng một lúc:
regions:batchUpdate
Điều kiện tiên quyết
Tất cả các yêu cầu hàng loạt đều yêu cầu vai trò người dùng QUẢN TRỊ để xác thực.
Tạo nhiều khu vực
Ví dụ này cho thấy cách tạo hai khu vực mới (một khu vực được xác định bằng mã bưu chính và một khu vực khác được xác định bằng tính năng nhắm mục tiêu theo địa lý) trong một lệnh gọi duy nhất của BatchCreateRegions.
Yêu cầu
Tạo URL yêu cầu như sau:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Nội dung yêu cầu chứa một danh sách requests, trong đó mỗi đối tượng chỉ định một regionId và dữ liệu region cần tạo.
{
"requests": [
{
"regionId": "seattle-area-98340",
"region": {
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
}
}
},
{
"regionId": "co-de-states",
"region": {
"displayName": "Colorado and Delaware",
"geoTargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
}
}
}
]
}
Phản hồi
Yêu cầu thành công sẽ trả về một danh sách các đối tượng region mới.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
"displayName": "Colorado and Delaware",
"geotargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
},
"regionalInventoryEligible": false,
"shippingEligible": false
}
]
}
Cập nhật nhiều khu vực
Ví dụ này cho thấy cách dùng BatchUpdateRegions để cập nhật displayName và postalCodeArea cho 2 khu vực hiện có. Bạn phải cung cấp region.name để cập nhật khu vực mục tiêu.
Yêu cầu
Tạo URL yêu cầu như sau:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Nội dung yêu cầu chứa một danh sách requests. Mỗi đối tượng phải chỉ định dữ liệu region cần cập nhật. Trường region.name phải chứa mã nhận dạng của khu vực cần cập nhật, ví dụ: "98005". Chỉ định tài nguyên là name thay vì accounts/{ACCOUNT_ID}/regions/name. Bạn không bắt buộc phải thêm updateMask để cho biết các trường cần thay đổi.
{
"requests": [
{
"region": {
"name": "98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
},
{
"region": {
"name": "07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
}
]
}
Phản hồi
Yêu cầu thành công sẽ trả về một danh sách các đối tượng region đã cập nhật.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
}
]
}
Xoá nhiều khu vực
Bạn có thể xoá nhiều khu vực trong một lệnh gọi duy nhất.
Yêu cầu
Ví dụ này cho thấy cách sử dụng BatchDeleteRegions để xoá 2 khu vực trong một lệnh gọi duy nhất.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Nội dung yêu cầu chứa một danh sách requests, trong đó mỗi đối tượng chỉ định name (không có "accounts/{ACCOUNT_ID}/regions/") của khu vực cần xoá.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Phản hồi
Một yêu cầu thành công sẽ trả về một nội dung phản hồi trống, cho biết rằng các khu vực được chỉ định đã bị xoá (hoặc không tồn tại).
{}
Các điểm hạn chế
Trước khi bắt đầu, hãy lưu ý những quy tắc sau:
- Thao tác nguyên tử: Các yêu cầu theo lô là nguyên tử. Nếu bất kỳ thao tác nào trong lô không thành công (ví dụ: một khu vực không tạo được), thì toàn bộ lô sẽ không thành công và không có thay đổi nào được thực hiện. API sẽ trả về một lỗi nêu chi tiết nguyên nhân gây ra lỗi.
- Giới hạn theo lô: Mỗi yêu cầu hàng loạt có thể chứa tối đa 100 thao tác theo khu vực.
- Hạn mức: Các điểm cuối này sử dụng cùng một nhóm hạn mức như các điểm cuối tương ứng có một thao tác (
regions.create,regions.delete,regions.update).
Các lỗi và vấn đề thường gặp
Sau đây là một số lỗi thường gặp và giải pháp cho những lỗi đó.
"Số lượng yêu cầu trong một lô quá lớn"
Lỗi này xảy ra nếu số lượng thao tác trong mảng yêu cầu của bạn vượt quá giới hạn 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Để khắc phục vấn đề này, hãy chia các thao tác thành nhiều yêu cầu hàng loạt có tối đa 100 thao tác.
Thiếu trường bắt buộc
Lỗi này xảy ra khi thiếu một trường bắt buộc. Thông báo lỗi chỉ định tham số bị thiếu.
Sau đây là các thông báo lỗi:
- Đối với
batchCreate:[regionId] Required parameter: regionId - Đối với
batchUpdate:[region.name] Required field not provided. - Đối với
batchDelete:[name] Required parameter: name
Để khắc phục vấn đề này, hãy xác minh rằng tất cả các trường bắt buộc đều có trong mỗi thao tác. Ví dụ: mọi mục trong yêu cầu batchUpdate đều phải có region.name.
Việc đăng yêu cầu sau đây sẽ dẫn đến lỗi:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Đã có khu vực sử dụng mã này"
Sẽ xảy ra lỗi nếu bạn cố gắng tạo một khu vực có regionId đã tồn tại.
Thông báo lỗi là [regionId] Region with specified id already exists..
Để khắc phục vấn đề này, hãy xác minh rằng tất cả các giá trị regionId đều là giá trị riêng biệt trong lô và không xung đột với các khu vực hiện có.
"Đã tìm thấy giá trị trùng lặp cho trường region.name hoặc regionId"
Lỗi sẽ xảy ra nếu bạn cố gắng tạo hoặc cập nhật nhiều khu vực có cùng mã trong một yêu cầu hàng loạt duy nhất.
Thông báo lỗi là Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Để khắc phục vấn đề này, hãy xác minh rằng tất cả các giá trị regionId (đối với batchCreate) hoặc region.name (đối với batchUpdate) đều là giá trị riêng biệt trong một yêu cầu hàng loạt.
"Không tìm thấy mục"
Khi sử dụng batchUpdate, nếu không có khu vực nào được chỉ định trong yêu cầu, thì toàn bộ lô sẽ gặp lỗi 404 NOT_FOUND. Điều này khác với batchDelete, sẽ thành công đối với các khu vực không tồn tại.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Để khắc phục vấn đề này, hãy xác minh rằng tất cả các khu vực mà bạn đang cố gắng cập nhật đều tồn tại trước khi gửi yêu cầu.