Регион 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/accounts/v1/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
}
]
}
В следующем примере показано, как создать несколько регионов в пакетном запросе:
Java
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.CreateRegionRequest;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea.PostalCodeRange;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to create multiple regions for a Merchant Center account. */
public class BatchCreateRegionsSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void batchCreateRegions(Config config, List<String> regionIds) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
RegionsServiceSettings regionsServiceSettings =
RegionsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to insert the regions.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (RegionsServiceClient regionsServiceClient =
RegionsServiceClient.create(regionsServiceSettings)) {
List<CreateRegionRequest> requests = new ArrayList<>();
for (String regionId : regionIds) {
requests.add(
CreateRegionRequest.newBuilder()
.setParent(parent)
.setRegionId(regionId)
.setRegion(
Region.newBuilder()
.setDisplayName("Region " + regionId)
.setPostalCodeArea(
PostalCodeArea.newBuilder()
.setRegionCode("US")
.addPostalCodes(
PostalCodeRange.newBuilder()
.setBegin("10001")
.setEnd("10282")
.build())
.build())
.build())
.build());
}
BatchCreateRegionsRequest request =
BatchCreateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();
System.out.println("Sending Batch Create Regions request");
BatchCreateRegionsResponse response = regionsServiceClient.batchCreateRegions(request);
System.out.println("Inserted Regions Names below");
// The last part of the region name will be the ID of the region.
// Format: `accounts/{account}/region/{region}`
response.getRegionsList().forEach(region -> System.out.println(region.getName()));
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// The unique IDs of the regions to create.
List<String> regionIds = new ArrayList<>();
regionIds.add("REGION_1");
regionIds.add("REGION_2");
regionIds.add("REGION_3");
regionIds.add("REGION_4");
regionIds.add("REGION_5");
batchCreateRegions(config, regionIds);
}
}
Обновление нескольких регионов
В этом примере показано, как использовать BatchUpdateRegions для обновления значений displayName и postalCodeArea для двух существующих регионов. Для обновления целевого региона необходимо указать region.name .
Запрос
Сформируйте URL-адрес запроса следующим образом:
POST https://merchantapi.googleapis.com/accounts/v1/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
}
]
}
В следующем примере показано, как обновить несколько регионов в пакетном запросе:
Java
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import com.google.shopping.merchant.accounts.v1.UpdateRegionRequest;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to update multiple regions for a Merchant Center account. */
public class BatchUpdateRegionsSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
private static String getRegionName(String accountId, String regionId) {
return String.format("accounts/%s/regions/%s", accountId, regionId);
}
public static void batchUpdateRegions(Config config, List<String> regionIds) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
RegionsServiceSettings regionsServiceSettings =
RegionsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to update the regions.
String parent = getParent(config.getAccountId().toString());
String accountId = config.getAccountId().toString();
// Calls the API and catches and prints any network failures/errors.
try (RegionsServiceClient regionsServiceClient =
RegionsServiceClient.create(regionsServiceSettings)) {
List<UpdateRegionRequest> requests = new ArrayList<>();
for (String regionId : regionIds) {
requests.add(
UpdateRegionRequest.newBuilder()
.setRegion(
Region.newBuilder()
.setName(getRegionName(accountId, regionId))
.setDisplayName("Updated Region " + regionId)
.build())
.setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build())
.build());
}
BatchUpdateRegionsRequest request =
BatchUpdateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();
System.out.println("Sending Batch Update Regions request");
BatchUpdateRegionsResponse response = regionsServiceClient.batchUpdateRegions(request);
System.out.println("Updated Regions Names below");
// The last part of the region name will be the ID of the region.
// Format: `accounts/{account}/region/{region}`
response.getRegionsList().forEach(region -> System.out.println(region.getName()));
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// The unique IDs of the regions to update.
List<String> regionIds = new ArrayList<>();
regionIds.add("REGION_1");
regionIds.add("REGION_2");
regionIds.add("REGION_3");
regionIds.add("REGION_4");
regionIds.add("REGION_5");
batchUpdateRegions(config, regionIds);
}
}
Удалить несколько регионов
Вы можете удалить несколько регионов за один вызов.
Запрос
В этом примере показано, как использовать BatchDeleteRegions для удаления двух регионов за один вызов.
POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchDelete
Тело запроса содержит список requests , где каждый объект указывает name (без "accounts/{ACCOUNT_ID}/regions/" ) региона, который необходимо удалить.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Ответ
В случае успешного выполнения запроса возвращается пустое тело ответа, указывающее на то, что указанные регионы были удалены (или не существовали).
{}
В следующем примере показано, как удалить несколько регионов в пакетном запросе:
Java
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchDeleteRegionsRequest;
import com.google.shopping.merchant.accounts.v1.DeleteRegionRequest;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to delete multiple regions for a Merchant Center account. */
public class BatchDeleteRegionsSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
private static String getRegionName(String accountId, String regionId) {
return String.format("accounts/%s/regions/%s", accountId, regionId);
}
public static void batchDeleteRegions(Config config, List<String> regionIds) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
RegionsServiceSettings regionsServiceSettings =
RegionsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to delete the regions.
String parent = getParent(config.getAccountId().toString());
String accountId = config.getAccountId().toString();
// Calls the API and catches and prints any network failures/errors.
try (RegionsServiceClient regionsServiceClient =
RegionsServiceClient.create(regionsServiceSettings)) {
List<DeleteRegionRequest> requests = new ArrayList<>();
for (String regionId : regionIds) {
requests.add(
DeleteRegionRequest.newBuilder().setName(getRegionName(accountId, regionId)).build());
}
BatchDeleteRegionsRequest request =
BatchDeleteRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();
System.out.println("Sending Batch Delete Regions request");
regionsServiceClient.batchDeleteRegions(request);
System.out.println("Regions deleted successfully");
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// The unique IDs of the regions to delete.
List<String> regionIds = new ArrayList<>();
regionIds.add("REGION_1");
regionIds.add("REGION_2");
regionIds.add("REGION_3");
regionIds.add("REGION_4");
regionIds.add("REGION_5");
batchDeleteRegions(config, regionIds);
}
}
Ограничения
Прежде чем начать, помните об этих правилах:
- Атомарные операции : Пакетные запросы являются атомарными. Если какая-либо отдельная операция в пакете завершится неудачей (например, не удастся создать один регион), весь пакет завершится неудачей , и никакие изменения не будут внесены. 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"
}
Чтобы исправить это, перед отправкой запроса убедитесь, что все регионы, которые вы пытаетесь обновить, существуют.