Управление региональным пакетированием

Регион API продавца представляет собой географический регион, который можно использовать в качестве целевого объекта для ресурса accounts.products.regionalInventories . Регионы можно определить как наборы почтовых индексов или, в некоторых странах, с помощью предопределенных геотаргетов. Подробнее см. в разделе «Настройка регионов» .

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 ).

Распространенные ошибки и проблемы

Вот несколько распространенных ошибок и их решений.

«Количество запросов в пакете слишком велико»

Эта ошибка возникает, если количество операций в массиве запросов превышает лимит в 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"
    }
  ]
}

«Регион с указанным ID уже существует»

При попытке создать регион с уже существующим 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"
}

Чтобы исправить это, перед отправкой запроса убедитесь, что все регионы, которые вы пытаетесь обновить, существуют.

Назад
Create and update regions