إدارة تجميع المناطق

تمثّل المنطقة في Merchant API منطقة جغرافية يمكنك استخدامها كهدف مرتبط بمورد accounts.products.regionalInventories. يمكنك تحديد المناطق كمجموعات من الرموز البريدية أو، في بعض البلدان، باستخدام أهداف جغرافية محدّدة مسبقًا. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد المناطق.

توفّر Merchant API نقاط نهاية مجمّعة لإدارة مناطقك، ما يسمح لك بإنشاء ما يصل إلى 100 منطقة وتعديلها وحذفها في طلب API واحد. ويُعدّ ذلك مثاليًا للتجّار الذين يديرون ميزة "تحديد السعر والتوفّر محليًا" (RAAP) على نطاق واسع، ما يحسّن الكفاءة ويبسّط عملية التكامل.

نظرة عامة

تتيح لك Batch API تنفيذ ما يلي باستخدام الطرق المرتبطة بها:

• إنشاء مناطق متعدّدة في طلب واحد: regions:batchCreate
• حذف مناطق متعدّدة في آنٍ واحد: regions:batchDelete
• تعديل مناطق متعدّدة في وقت واحد: regions:batchUpdate

المتطلبات الأساسية

تتطلّب جميع الطلبات المجمّعة دور مستخدم المشرف للمصادقة.

إنشاء مناطق متعدّدة

يوضّح هذا المثال كيفية إنشاء منطقتَين جديدتَين في طلب واحد من 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". حدِّد المورد على أنّه name بدلاً من accounts/{ACCOUNT_ID}/regions/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"
    }
   ]
}

الردّ

يعرض الطلب الناجح نص ردّ فارغًا، ما يشير إلى أنّه تم حذف المناطق المحدّدة (أو أنّها لم تكن متوفّرة).

{}

القيود

قبل البدء، ضَع هذه القواعد في الاعتبار:

• العمليات الذرّية: الطلبات المجمّعة هي عمليات ذرّية. إذا فشلت أي عملية فردية ضمن الطلب المجمّع (على سبيل المثال، تعذّر إنشاء منطقة واحدة)، سيفشل الطلب المجمّع بأكمله ولن يتم إجراء أي تغييرات. ستعرض واجهة برمجة التطبيقات خطأً يوضّح سبب الفشل.
• الحدود المجمّعة: يمكن أن يحتوي كل طلب مجمّع على 100 عملية منطقة كحدّ أقصى.
• الحصص: تستخدم نقاط النهاية هذه مجموعات الحصص نفسها التي تستخدمها نظيراتها من العمليات الفردية (regions.create وregions.delete وregions.update).

الأخطاء والمشاكل الشائعة

في ما يلي بعض المشاكل الشائعة وحلولها.

"The number of requests in a batch is too large"

يحدث هذا الخطأ إذا كان عدد العمليات في مصفوفة الطلبات يتجاوز الحدّ الأقصى البالغ 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"
    }
  ]
}

"Region with specified ID already exists"

يحدث خطأ إذا حاولت إنشاء منطقة باستخدام regionId موجود من قبل.

رسالة الخطأ هي [regionId] Region with specified id already exists..

لحلّ هذه المشكلة، تأكَّد من أنّ جميع قيم regionId فريدة ضمن الطلب المجمّع ولا تتعارض مع المناطق الحالية.

"Duplicate value found for field region.name or regionId found"

يحدث خطأ إذا حاولت إنشاء مناطق متعدّدة أو تعديلها باستخدام رقم التعريف نفسه ضمن طلب مجمّع واحد.

رسالة الخطأ هي 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"
}

لحلّ هذه المشكلة، تأكَّد من أنّ جميع المناطق التي تحاول تعديلها متوفّرة قبل إرسال الطلب.