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

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

رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) نقاط پایانی دسته‌ای را برای مدیریت مناطق شما فراهم می‌کند و به شما امکان می‌دهد تا ۱۰۰ منطقه را در یک فراخوانی 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". منبع را به جای 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 خطایی را برمی‌گرداند که علت شکست را شرح می‌دهد.
  • محدودیت‌های دسته‌ای : هر درخواست دسته‌ای می‌تواند حداکثر شامل ۱۰۰ عملیات منطقه‌ای باشد.
  • سهمیه‌ها : این نقاط پایانی از همان گروه‌های سهمیه‌ای استفاده می‌کنند که همتایان تک عملیاتی آنها ( regions.create ، regions.delete ، regions.update ) از آن استفاده می‌کنند.

خطاها و مشکلات رایج

در اینجا به چند مورد از اشتباهات رایج و راه حل های آنها اشاره می کنیم.

«تعداد درخواست‌ها در یک دسته خیلی زیاد است»

این خطا زمانی رخ می‌دهد که تعداد عملیات موجود در آرایه درخواست‌های شما از حد مجاز ۱۰۰ تجاوز کند. 

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

برای رفع این مشکل، عملیات خود را به چندین درخواست دسته‌ای ۱۰۰ تایی یا کمتر تقسیم کنید.

فیلد مورد نیاز موجود نیست

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

پیام‌های خطا به شرح زیر هستند:

  • برای 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"
}

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

قبلی
Create and update regions
بعدی
Manage Merchant Center email preferences