التعامل مع ردود الأخطاء

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

نظرة عامة

عند تعذُّر طلب بيانات من Merchant API، تعرض واجهة برمجة التطبيقات رمز حالة HTTP عاديًا (4xx أو 5xx) ونص استجابة JSON يحتوي على تفاصيل حول الخطأ. تتّبع Merchant API معيار AIP-193 لتفاصيل الأخطاء، ما يوفّر معلومات يمكن معالجتها آليًا تتيح لتطبيقك التعامل مع سيناريوهات أخطاء معيّنة آليًا.

ملاحظة: يتم طرح بنية الاستجابة للخطأ هذه تدريجيًا في Merchant API. تتّبع الأخطاء التي تعرضها واجهات برمجة التطبيقات الفرعية Products وReports وData sources فقط التنسيق الموضّح هنا. قد تظل الأخطاء من واجهات برمجة التطبيقات الفرعية الأخرى بتنسيق قديم وقد لا تتضمّن البيانات الوصفية ErrorInfo.

بنية ردّ الخطأ

يكون ردّ الخطأ عبارة عن عنصر JSON يحتوي على حقول عادية، مثل code وmessage وstatus. والأهم من ذلك، أنّه يتضمّن أيضًا مصفوفة details. للتعامل مع الأخطاء آليًا، عليك البحث عن عنصر ضمن details حيث تكون قيمة @type هي type.googleapis.com/google.rpc.ErrorInfo.

يوفّر كائن ErrorInfo هذا بيانات منظَّمة وثابتة حول الخطأ:

• domain: التجميع المنطقي للخطأ، عادةً merchantapi.googleapis.com.
• metadata: خريطة للقيم الديناميكية ذات الصلة بالخطأ. يشمل ذلك ما يلي:
  • REASON: معرّف محدّد وثابت للخطأ نفسه (مثل INVALID_NAME_PART_NOT_NUMBER وPERMISSION_DENIED_ACCOUNTS). يتوفّر هذا الحقل دائمًا. استخدِم هذا الحقل لمعالجة الأخطاء بدقة في منطق تطبيقك.
  • ‫HELP_CENTER_LINK: يوفّر سياقًا وتعليمات إضافية لحلّ المشكلة. لا يتوفّر هذا الحقل لجميع الأخطاء، ولكنّنا نخطّط لتوسيع نطاق تغطيته بمرور الوقت ليشمل الأخطاء التي قد تتطلّب المزيد من السياق.
  • الحقول الديناميكية الأخرى: مفاتيح أخرى توفّر سياقًا، مثل اسم الحقل غير الصالح (FIELD_LOCATION) أو القيمة التي تسبّبت في حدوث الخطأ (FIELD_VALUE).

أمثلة على ردود الخطأ

يوضّح ملف JSON التالي بنية خطأ في Merchant API حيث تم تنسيق اسم المورد بشكل غير صحيح.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

في ما يلي مثال على خطأ في المصادقة:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

ثبات حقول الأخطاء

عند كتابة منطق معالجة الأخطاء، من المهم معرفة الحقول التي يمكن الاعتماد عليها بأمان وتلك التي قد تتغيّر.

• الحقول الثابتة:

• ‫details.metadata.REASON: معرّف الخطأ المحدّد يجب الاعتماد على هذا الحقل في منطق تدفق التحكم في تطبيقك.

  • مفاتيح details.metadata: المفاتيح ضمن خريطة البيانات الوصفية (مثل FIELD_LOCATION وACCOUNT_IDS) ثابتة.
  • code: رمز حالة HTTP العالي المستوى (مثل 400 و401 و503) ثابت.

• الحقول غير الثابتة:

  • message: رسالة الخطأ التي يمكن لشخص عادي قراءتها ليست ثابتة. وهي مخصّصة لتصحيح أخطاء المطوّرين فقط. لا تكتب رمزًا برمجيًا يحلّل المحتوى النصي للحقل message أو يعتمد عليه، لأنّه قد يتغيّر بدون إشعار لتحسين الوضوح أو إضافة سياق.
  • قيم details.metadata: على الرغم من أنّ المفاتيح ثابتة، قد تتغيّر القيم للمفاتيح المعلوماتية. على سبيل المثال، إذا تم توفير مفتاح HELP_CENTER_LINK، قد يتم تعديل عنوان URL المحدّد الذي يشير إليه إلى صفحة مستندات أحدث بدون إشعار مسبق. ومع ذلك، كما ذكرنا سابقًا، فإنّ قيمة details.metadata.REASON ثابتة.

أفضل الممارسات

اتّبِع أفضل الممارسات التالية لضمان معالجة عملية الدمج للأخطاء بشكل سلس.

استخدام details.metadata.REASON للمنطق

استخدِم دائمًا السمة REASON المحدّدة داخل خريطة metadata لتحديد سبب الخطأ. لا تعتمد على رمز حالة HTTP وحده، لأنّ أخطاء متعددة قد تشترك في رمز الحالة نفسه.

عدم تحليل رسالة الخطأ

كما هو موضّح في قسم الثبات، الحقل message مخصّص للاستخدام البشري. إذا كنت بحاجة إلى معلومات ديناميكية (مثل الحقل غير الصالح)، يمكنك استخراجها من الخريطة metadata باستخدام مفاتيح ثابتة مثل FIELD_LOCATION وVARIABLE_NAME.

تنفيذ خوارزمية الرقود الأسي الثنائي

بالنسبة إلى الأخطاء التي تشير إلى عدم التوفّر المؤقت أو الحدّ من المعدّل، يمكنك تنفيذ استراتيجية تأخير أسي. ويعني ذلك الانتظار لفترة قصيرة قبل إعادة المحاولة، وزيادة وقت الانتظار مع كل محاولة فاشلة لاحقة.

• quota/request_rate_too_high: يشير هذا الخطأ إلى أنّك تجاوزت الحصة بالدقيقة لمجموعة حصص معيّنة. يُرجى إبطاء معدّل الطلبات.
• ‫internal_error: عادةً ما تكون هذه الأخطاء مؤقتة. يُرجى إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.

ملاحظة: إذا استمر ظهور الخطأ internal_error بعد عدة محاولات مع تأخير، يُرجى الاطّلاع على كيفية التواصل مع فريق دعم Merchant API.

كيفية التواصل مع فريق دعم Merchant API

إذا كنت بحاجة إلى التواصل مع فريق دعم Merchant API بشأن خطأ معيّن، يُرجى تقديم المعلومات التالية في طلبك:

1. ردّ الخطأ الدقيق الذي تم تلقّيه
2. اسم طريقة واجهة برمجة التطبيقات
3. حمولة الطلب
4. الطوابع الزمنية أو النطاق الزمني الذي تم فيه استدعاء الطريقة وتلقّي الأخطاء