Zarządzanie grupowaniem regionów

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

Interfejs Merchant API udostępnia punkty końcowe do zarządzania regionami, które umożliwiają tworzenie, aktualizowanie i usuwanie maksymalnie 100 regionów w ramach jednego wywołania interfejsu API. Jest to idealne rozwiązanie dla sprzedawców, którzy zarządzają regionalną dostępnością i cenami na dużą skalę, ponieważ 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 zbiorcze wymagają do uwierzytelniania 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ą BatchUpdateRegions zaktualizować 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 1 wywołaniu.

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ź

Pomyślne żądanie 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 pakietu zakończy się niepowodzeniem (np. nie uda się utworzyć regionu), cały pakiet 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 zbyt duża”

Ten błąd występuje, jeśli liczba operacji w tablicy żądań przekracza limit wynoszący 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ń wsadowych zawierających maksymalnie 100 operacji.

Wymagane pole jest puste

Ten błąd występuje, gdy brakuje wymaganego pola. Komunikat o błędzie określa brakujący parametr.

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 znajdują się 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”

Błąd wystąpi, jeśli spróbujesz utworzyć region z regionId, który już istnieje.

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

Aby rozwiązać ten problem, sprawdź, czy wszystkie wartości regionId są niepowtarzalne w ramach partii i nie kolidują z istniejącymi regionami.

„Znaleziono zduplikowaną wartość w polu region.name lub regionId”

Jeśli w ramach jednego żądania zbiorczego spróbujesz utworzyć lub zaktualizować wiele 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ą niepowtarzalne w ramach pojedynczego żądania zbiorczego.

„Nie znaleziono elementu”

Jeśli używasz batchUpdate, a którykolwiek region określony w żądaniu nie istnieje, cały pakiet zakończy się niepowodzeniem z błędem 404 NOT_FOUND. Różni się to od batchDelete, które działa 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ą.