Zarządzanie grupowaniem regionów

Region Merchant API to region geograficzny, którego możesz używać jako celu powiązanego z zasobem accounts.products.regionalInventories. Regiony możesz definiować jako zbiory kodów pocztowych lub w niektórych krajach za pomocą wstępnie zdefiniowanych geotargetów. Więcej informacji znajdziesz w artykule Konfigurowanie regionów.

Interfejs Merchant API udostępnia punkty końcowe do przetwarzania zbiorczego, które umożliwiają zarządzanie regionami. Możesz tworzyć, aktualizować i usuwać maksymalnie 100 regionów w ramach jednego wywołania interfejsu API. Jest to idealne rozwiązanie dla sprzedawców zarządzających regionalną dostępnością i cenami na dużą skalę, które zwiększa wydajność i upraszcza integrację.

Przegląd

Interfejs Batch API umożliwia wykonywanie tych czynności za pomocą powiązanych metod:

  • Utwórz kilka regionów w jednym żądaniu: regions:batchCreate
  • Usuwanie wielu regionów jednocześnie: regions:batchDelete
  • Aktualizowanie wielu regionów jednocześnie: regions:batchUpdate

Wymagania wstępne

Wszystkie żądania wsadowe wymagają do uwierzytelnienia roli użytkownika ADMIN.

Tworzenie wielu regionów

Ten przykład pokazuje, jak utworzyć 2 nowe regiony – jeden zdefiniowany przez kody pocztowe, a drugi przez kierowanie geograficzne – w ramach jednego wywołania funkcji BatchCreateRegions.

Żądanie

Utwórz adres URL żądania w ten sposób:

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate

Treść żądania zawiera listę obiektów requests, z których każdy określa regionId i dane region do utworzenia.

{
  "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"
          ]
        }
      }
    }
  ]
}

Odpowiedź

Żądanie zakończone pomyślnie zwraca listę nowych obiektów 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
    }
  ]
}

Aktualizowanie wielu regionów

Ten przykład pokazuje, jak za pomocą parametru BatchUpdateRegions zaktualizować parametry displayName i postalCodeArea w przypadku 2 istniejących regionów. Aby zaktualizować region docelowy, musisz podać region.name.

Żądanie

Utwórz adres URL żądania w ten sposób:

POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate

Treść żądania zawiera listę requests. Każdy obiekt musi określać regiondane do zaktualizowania. Pole region.name musi zawierać identyfikator regionu do zaktualizowania, np. „98005”. Określ zasób jako name, a nie accounts/{ACCOUNT_ID}/regions/name. Dodanie updateMask w celu wskazania pól do zmiany jest opcjonalne.

{
  "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"
    }
  ]
}

Odpowiedź

Żądanie zakończone pomyślnie zwraca listę zaktualizowanych obiektów 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
    }
  ]
}

Usuwanie wielu regionów

W jednym wywołaniu możesz usunąć wiele regionów.

Żądanie

Ten przykład pokazuje, jak za pomocą BatchDeleteRegions usunąć 2 regiony w ramach jednego wywołania.

POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete

Treść żądania zawiera listę obiektów requests, z których każdy określa name (bez "accounts/{ACCOUNT_ID}/regions/") regionu do usunięcia.

{
  "requests":
   [
    {
      "name": "98005"
    },
    {
      "name": "07086"
    }
   ]
}

Odpowiedź

Żądanie zakończone pomyślnie zwraca pustą treść odpowiedzi, co oznacza, że określone regiony zostały usunięte (lub nie istniały).

{}

Ograniczenia

Zanim zaczniesz, pamiętaj o tych zasadach:

  • Operacje niepodzielne: żądania wsadowe są niepodzielne. Jeśli jakakolwiek operacja w ramach partii zakończy się niepowodzeniem (np. nie uda się utworzyć regionu), cała partia zakończy się niepowodzeniem i nie zostaną wprowadzone żadne zmiany. Interfejs API zwróci błąd z informacją o przyczynie niepowodzenia.
  • Limity żądań zbiorczych: każde żądanie zbiorcze może zawierać maksymalnie 100 operacji w regionie.
  • Limity: te punkty końcowe korzystają z tych samych grup limitów co ich odpowiedniki z jedną operacją (regions.create, regions.delete, regions.update).

Typowe błędy i problemy

Oto kilka typowych problemów i ich rozwiązań.

„Liczba żądań w partii jest za duża”

Ten błąd występuje, jeśli liczba operacji w tablicy żądań przekracza limit 100.

"error":
  {
    "code": 400,
    "message": "The number of requests in a batch is too large.",
    "status": "INVALID_ARGUMENT"
  }

Aby rozwiązać ten problem, podziel operacje na kilka żądań zbiorczych, z których każde będzie zawierać maksymalnie 100 operacji.

Wymagane pole jest puste

Ten błąd pojawia się, gdy brakuje wymaganego pola. Komunikat o błędzie zawiera informację o brakującym parametrze.

Komunikaty o błędach:

  • batchCreate za [regionId] Required parameter: regionId
  • batchUpdate za [region.name] Required field not provided.
  • batchDelete za [name] Required parameter: name

Aby to naprawić, sprawdź, czy w każdej operacji występują wszystkie wymagane pola. Na przykład każdy wpis w żądaniu batchUpdate musi zawierać region.name. Wysłanie tego żądania spowoduje błąd:

{
  "requests":
  [
    {
      "region":
        {
          "displayName": "An update without a region name"
        },
        "updateMask": "displayName"
    }
  ]
}

„Region o podanym identyfikatorze już istnieje”

Jeśli spróbujesz utworzyć region z regionId, który już istnieje, pojawi się błąd.

Komunikat o błędzie to [regionId] Region with specified id already exists..

Aby to naprawić, sprawdź, czy wszystkie wartości regionId w partii są niepowtarzalne i nie kolidują z istniejącymi regionami.

„Zduplikowana wartość w polu region.name lub regionId”

Jeśli w ramach jednego żądania zbiorczego spróbujesz utworzyć lub zaktualizować kilka regionów o tym samym identyfikatorze, wystąpi błąd.

Komunikat o błędzie to Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

Aby rozwiązać ten problem, sprawdź, czy wszystkie wartości regionId (w przypadku batchCreate) lub region.name (w przypadku batchUpdate) są unikalne w ramach pojedynczego żądania zbiorczego.

„Nie znaleziono elementu”

Jeśli podczas korzystania z batchUpdate którykolwiek region określony w żądaniu nie istnieje, cała partia zakończy się niepowodzeniem z błędem 404 NOT_FOUND. Ten powód różni się od batchDelete, który jest zwracany w przypadku nieistniejących regionów.

"error": {
    "code": 404,
    "message": "item not found",
    "status": "NOT_FOUND"
}

Aby to naprawić, przed wysłaniem prośby sprawdź, czy wszystkie regiony, które próbujesz zaktualizować, istnieją.

Wstecz
Create and update regions