Khu vực Merchant API đại diện cho một khu vực địa lý mà bạn có thể sử 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 các khu vực là tập hợp mã bưu chính hoặc ở một số quốc gia, sử dụng các mục tiêu đị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 theo lô để 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. Điều này rất phù hợp với 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á quá trình tích hợp.
Tổng quan
API theo lô cho phép bạn thực hiện những việc sau bằng các phương thức liên quan:
- Tạo nhiều khu vực trong một yêu cầu:
regions:batchCreate - Xoá nhiều khu vực cùng một lúc:
regions:batchDelete - Cập nhật nhiều khu vực cùng lúc:
regions:batchUpdate
Điều kiện tiên quyết
Tất cả các yêu cầu theo lô đều yêu cầu vai trò người dùng ADMIN để xác thực.
Tạo nhiều khu vực
Ví dụ này minh hoạ cách tạo 2 khu vực mới (một khu vực được xác định theo mã bưu chính và một khu vực được xác định theo tính năng nhắm mục tiêu theo vị trí địa lý) trong một lệnh gọi BatchCreateRegions.
Yêu cầu
Xây dựng 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 để 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 minh hoạ cách sử 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
Xây dựng 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ập nhật. Trường region.name phải chứa mã 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 có thể đưa updateMask vào để 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.
Yêu cầu
Ví dụ này minh hoạ cách sử dụng BatchDeleteRegions để xoá 2 khu vực trong một lệnh gọi.
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
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 dạng nguyên tử: Các yêu cầu theo lô là thao tác dạng nguyên tử. Nếu bất kỳ thao tác nào trong lô không thành công (ví dụ: không tạo được một khu vực), thì toàn bộ lô sẽ không thành công và sẽ 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 theo lô có thể chứa tối đa 100 thao tác 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 cho
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à cách khắc phục.
"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 lỗi này, hãy chia các thao tác thành nhiều yêu cầu theo lô, mỗi lô có 100 thao tác trở xuống.
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 lỗi 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 nhập trong yêu cầu batchUpdate đều phải bao gồm 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ó một khu vực sử dụng mã được chỉ định"
Lỗi xảy ra 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 lỗi này, hãy xác minh rằng tất cả các giá trị regionId đều là duy nhấ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 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ột mã trong một yêu cầu theo lô.
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 lỗi 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à duy nhất trong một yêu cầu theo lô.
"Không tìm thấy mục nào"
Khi sử dụng batchUpdate, nếu bất kỳ khu vực nào được chỉ định trong yêu cầu không tồn tại, thì toàn bộ lô sẽ không thành công và gặp lỗi 404 NOT_FOUND. Điều này khác với batchDelete, thao tác này 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 lỗi 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.