Bölge gruplandırmayı yönetme

Bir Merchant API bölgesi, accounts.products.regionalInventories kaynağıyla ilgili bir hedef olarak kullanabileceğiniz bir coğrafi bölgeyi temsil eder. Bölgeleri posta kodu koleksiyonları veya bazı ülkelerde önceden tanımlanmış coğrafi hedeflemeler kullanarak tanımlayabilirsiniz. Daha fazla bilgi için Bölgeleri ayarlama başlıklı makaleyi inceleyin.

Merchant API, bölgelerinizi yönetmek için toplu uç noktalar sağlar. Bu sayede tek bir API çağrısında 100 adede kadar bölge oluşturabilir, güncelleyebilir ve silebilirsiniz. Bu özellik, bölgesel stok durumu ve fiyatlandırmayı (RAAP) büyük ölçekte yöneten, verimliliği artıran ve entegrasyonu basitleştiren satıcılar için idealdir.

Genel Bakış

Batch API, ilişkili yöntemlerle aşağıdakileri yapmanıza olanak tanır:

  • Tek bir istekte birden fazla bölge oluşturma: regions:batchCreate
  • Aynı anda birden fazla bölgeyi silme: regions:batchDelete
  • Birden fazla bölgeyi aynı anda güncelleme: regions:batchUpdate

Ön koşullar

Tüm toplu istekler için kimlik doğrulama amacıyla ADMIN kullanıcı rolü gerekir.

Birden fazla bölge oluşturma

Bu örnekte, BatchCreateRegions tek bir çağrısında posta kodlarıyla tanımlanan bir bölge ve coğrafi hedeflemeyle tanımlanan başka bir bölge olmak üzere iki yeni bölgenin nasıl oluşturulacağı gösterilmektedir.

İstek

İstek URL'sini aşağıdaki gibi oluşturun:

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

İstek gövdesi, her nesnenin oluşturulacak regionId ve region verilerini belirttiği bir requests listesi içerir.

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

Yanıt

Başarılı bir istek, yeni region nesnelerinin listesini döndürür.

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

Birden fazla bölgeyi güncelleme

Bu örnekte, iki mevcut bölgenin displayName ve postalCodeArea değerlerini güncellemek için BatchUpdateRegions özelliğinin nasıl kullanılacağı gösterilmektedir. Hedeflenen bölgeyi güncellemek için bir region.name sağlamanız gerekir.

İstek

İstek URL'sini aşağıdaki gibi oluşturun:

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

İstek metni, requests listesini içerir. Her nesne, güncellenecek region verilerini belirtmelidir. region.name alanı, güncellenecek bölgenin kimliğini içermelidir. Örneğin,"98005". Kaynağı accounts/{ACCOUNT_ID}/regions/name yerine name olarak belirtin. Değiştirilecek alanları belirtmek için updateMask eklemek isteğe bağlıdır.

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

Yanıt

Başarılı bir istek, güncellenen region nesnelerinin listesini döndürür.

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

Birden fazla bölgeyi silme

Tek bir çağrıda birden fazla bölgeyi silebilirsiniz.

İstek

Bu örnekte, tek bir çağrıyla iki bölgeyi silmek için BatchDeleteRegions yönteminin nasıl kullanılacağı gösterilmektedir.

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

İstek gövdesi, requests listesini içerir. Her nesne, silinecek bölgenin name değerini ("accounts/{ACCOUNT_ID}/regions/" olmadan) belirtir.

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

Yanıt

Başarılı bir istek, belirtilen bölgelerin silindiğini (veya mevcut olmadığını) gösteren boş bir yanıt gövdesi döndürür.

{}

Sınırlamalar

Başlamadan önce aşağıdaki kuralları göz önünde bulundurun:

  • Atomik işlemler: Toplu istekler atomiktir. Toplu işlemdeki tek bir işlem başarısız olursa (örneğin, bir bölge oluşturulamazsa) toplu işlemin tamamı başarısız olur ve hiçbir değişiklik yapılmaz. API, hatanın nedenini açıklayan bir hata döndürür.
  • Toplu işlem sınırları: Her toplu istek en fazla 100 bölge işlemi içerebilir.
  • Kotalar: Bu uç noktalar, tek işlemli benzerleriyle (regions.create, regions.delete, regions.update) aynı kota gruplarını kullanır.

Sık karşılaşılan hatalar ve sorunlar

Sık karşılaşılan bazı hatalar ve çözümleri aşağıda açıklanmıştır.

"Bir toplu işlemdeki istek sayısı çok fazla"

Bu hata, istekler dizinizdeki işlem sayısı 100 sınırını aştığında oluşur.

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

Bu sorunu düzeltmek için işlemlerinizi 100 veya daha az öğe içeren birden fazla toplu isteğe bölün.

Zorunlu alan boş bırakılmış

Bu hata, zorunlu bir alan eksik olduğunda oluşur. Hata mesajında eksik parametre belirtilir.

Hata mesajları şunlardır:

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

Bu sorunu düzeltmek için her işlemde tüm zorunlu alanların bulunduğunu doğrulayın. Örneğin, batchUpdate isteğindeki her giriş region.name değerini içermelidir. Aşağıdaki isteğin yayınlanması hataya neden olur:

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

"Belirtilen kimliğe sahip bölge zaten mevcut"

Halihazırda mevcut olan bir regionId ile bölge oluşturmaya çalışırsanız hata oluşur.

Hata mesajı [regionId] Region with specified id already exists..

Bu sorunu düzeltmek için tüm regionId değerlerinin toplu işlem içinde benzersiz olduğunu ve mevcut bölgelerle çakışmadığını doğrulayın.

"Duplicate value found for field region.name or regionId found" ("Bölge.adı veya bölge kimliği alanı için yinelenen değer bulundu")

Tek bir toplu istekte aynı kimliğe sahip birden fazla bölge oluşturmaya veya güncellemeye çalışırsanız hata oluşur.

Hata mesajı Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

Bu sorunu düzeltmek için tüm regionId (batchCreate için) veya region.name (batchUpdate için) değerlerinin tek bir toplu istek içinde benzersiz olduğunu doğrulayın.

"Öğe bulunamadı"

batchUpdate kullanılırken istekte belirtilen bölgelerden herhangi biri yoksa toplu işlemin tamamı 404 NOT_FOUND hatasıyla başarısız olur. Bu, var olmayan bölgelerde başarılı olan batchDelete işleminden farklıdır.

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

Bu sorunu düzeltmek için isteği göndermeden önce güncellemeye çalıştığınız tüm bölgelerin mevcut olduğunu doğrulayın.

Önceki
Create and update regions