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

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

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

نظرة عامة

تتيح لك 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).

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

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

"عدد الطلبات في المجموعة كبير جدًا"

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

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

السابق
Create and update regions