Регион Merchant API представляет собой географический регион, который можно использовать в качестве целевого объекта для ресурса accounts.products.regionalInventories . Вы можете определять регионы как наборы почтовых индексов или, в некоторых странах, используя предопределенные геоцелевые объекты. Для получения дополнительной информации см. раздел «Настройка регионов» .
Merchant API предоставляет пакетные конечные точки для управления регионами, позволяя создавать, обновлять и удалять до 100 регионов за один вызов API. Это идеально подходит для продавцов, управляющих региональной доступностью и ценообразованием (RAAP) в больших масштабах, повышая эффективность и упрощая интеграцию.
Обзор
API пакетной обработки позволяет выполнять следующие действия с помощью соответствующих методов:
- Создайте несколько регионов в одном запросе:
regions:batchCreate - Удаление нескольких регионов одновременно:
regions:batchDelete - Обновить несколько регионов одновременно:
regions:batchUpdate
Предварительные требования
Для аутентификации при выполнении всех пакетных запросов требуется роль пользователя ADMIN .
Создайте несколько регионов
В этом примере показано, как создать два новых региона — один, определяемый почтовыми индексами, а другой — географическим таргетингом — за один вызов функции BatchCreateRegions .
Запрос
Сформируйте URL-адрес запроса следующим образом:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Тело запроса содержит список requests , где каждый объект указывает regionId и данные region для создания.
{
"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"
]
}
}
}
]
}
Ответ
В случае успешного выполнения запроса возвращается список новых объектов region .
{
"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
}
]
}
Обновление нескольких регионов
В этом примере показано, как использовать BatchUpdateRegions для обновления значений displayName и postalCodeArea для двух существующих регионов. Для обновления целевого региона необходимо указать region.name .
Запрос
Сформируйте URL-адрес запроса следующим образом:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Тело запроса содержит список requests . Каждый объект должен указывать данные region для обновления. Поле region.name должно содержать идентификатор региона для обновления, например, "98005". Укажите ресурс в качестве name , а не accounts/{ACCOUNT_ID}/regions/name . Включение updateMask для указания полей для изменения является необязательным.
{
"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"
}
]
}
Ответ
В случае успешного выполнения запроса возвращается список обновленных объектов region .
{
"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
}
]
}
Удалить несколько регионов
Вы можете удалить несколько регионов за один вызов.
Запрос
В этом примере показано, как использовать BatchDeleteRegions для удаления двух регионов за один вызов.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Тело запроса содержит список requests , где каждый объект указывает name (без "accounts/{ACCOUNT_ID}/regions/" ) региона, который необходимо удалить.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Ответ
В случае успешного выполнения запроса возвращается пустое тело ответа, указывающее на то, что указанные регионы были удалены (или не существовали).
{}
Ограничения
Прежде чем начать, помните об этих правилах:
- Атомарные операции : Пакетные запросы являются атомарными. Если какая-либо отдельная операция в пакете завершится неудачей (например, не удастся создать один регион), весь пакет завершится неудачей , и никакие изменения не будут внесены. API вернет ошибку с подробным описанием причины сбоя.
- Ограничения по пакетной обработке : каждый пакетный запрос может содержать максимум 100 операций с регионами.
- Квоты : Эти конечные точки используют те же группы квот, что и их аналоги, выполняющие одну операцию (
regions.create,regions.delete,regions.update).
Распространенные ошибки и проблемы
Вот несколько распространенных ошибок и способы их решения.
"Количество запросов в пакете слишком велико"
Эта ошибка возникает, если количество операций в массиве requests превышает лимит в 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Чтобы исправить это, разделите ваши операции на несколько пакетных запросов по 100 или менее запросов.
Отсутствует обязательное поле.
Эта ошибка возникает, когда отсутствует обязательное поле. В сообщении об ошибке указывается отсутствующий параметр.
Сообщения об ошибках выглядят следующим образом:
- Для
batchCreate:[regionId] Required parameter: regionId - Для
batchUpdate:[region.name] Required field not provided. - Для
batchDelete:[name] Required parameter: name
Чтобы исправить это, убедитесь, что все необходимые поля присутствуют в каждой операции. Например, каждая запись в запросе batchUpdate должна включать region.name . Отправка следующего запроса приводит к ошибке:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Регион с указанным идентификатором уже существует"
Ошибка возникнет, если вы попытаетесь создать регион с уже существующим regionId .
Сообщение об ошибке: [regionId] Region with specified id already exists.
Для решения этой проблемы убедитесь, что все значения regionId в рамках пакета уникальны и не конфликтуют с существующими регионами.
"Обнаружено повторяющееся значение для поля region.name или regionId"
Ошибка возникает при попытке создать или обновить несколько регионов с одним и тем же идентификатором в рамках одного пакетного запроса.
Сообщение об ошибке: Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}.
Чтобы исправить это, убедитесь, что все значения regionId (для batchCreate ) или region.name (для batchUpdate ) уникальны в рамках одного пакетного запроса.
"Элемент не найден"
При использовании batchUpdate , если какой-либо регион, указанный в запросе, не существует, весь пакет завершится с ошибкой 404 NOT_FOUND . Это отличается от batchDelete , который успешно обрабатывает несуществующие регионы.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Чтобы исправить это, перед отправкой запроса убедитесь, что все регионы, которые вы пытаетесь обновить, существуют.