دسته بندی منطقه را مدیریت کنید

یک منطقه Merchant API یک منطقه جغرافیایی را نشان می دهد که می توانید از آن به عنوان هدف مرتبط با منبع accounts.products.regionalInventories استفاده کنید. می‌توانید مناطق را به‌عنوان مجموعه‌ای از کدهای پستی یا در برخی کشورها با استفاده از اهداف جغرافیایی از پیش تعریف‌شده تعریف کنید. برای اطلاعات بیشتر، به تنظیم مناطق مراجعه کنید.

Merchant API نقاط پایانی دسته‌ای را برای مدیریت مناطق شما فراهم می‌کند و به شما امکان می‌دهد تا 100 منطقه را در یک تماس API ایجاد، به‌روزرسانی و حذف کنید. این برای بازرگانی که در دسترس بودن و قیمت گذاری منطقه ای (RAAP) را در مقیاس مدیریت می کنند، کارایی را بهبود می بخشد و یکپارچگی را ساده می کند، ایده آل است.

نمای کلی

Batch 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". منبع را به‌جای accounts/{ACCOUNT_ID}/regions/name به‌عنوان 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"
    }
  ]
}

"منطقه با شناسه مشخص شده از قبل وجود دارد"

اگر بخواهید منطقه ای با یک 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"
}

برای رفع این مشکل، قبل از ارسال درخواست، بررسی کنید که همه مناطقی که می‌خواهید به‌روزرسانی کنید وجود داشته باشند.