التعرّف على أخطاء واجهة برمجة التطبيقات

يوضّح هذا الدليل كيفية معالجة الأخطاء وإرسال إشعارات بشأنها في Google Ads API. إنّ فهم بنية أخطاء واجهة برمجة التطبيقات ومعناها أمر بالغ الأهمية لإنشاء تطبيقات قوية يمكنها التعامل مع المشاكل بسلاسة، بدءًا من الإدخال غير الصالح إلى عدم توفّر الخدمة مؤقتًا.

تتّبع Google Ads API نموذج الأخطاء العادي في Google API، والذي يستند إلى رموز الحالة في gRPC. يتضمّن كل ردّ من واجهة برمجة التطبيقات يؤدي إلى حدوث خطأ عنصر Status يحتوي على ما يلي:

• رمز خطأ رقمي
• رسالة خطأ
• تفاصيل إضافية اختيارية عن الخطأ

رموز الخطأ المتعلقة بالعناوين الأساسية

تستخدِم Google Ads API مجموعة من رموز الخطأ الأساسية التي يحدّدها gRPC وHTTP. تقدّم هذه الرموز إشارة عالية المستوى إلى نوع الخطأ. يجب دائمًا التحقّق من هذا الرمز الرقمي أولاً لفهم الطبيعة الأساسية للمشكلة.

يلخّص الجدول التالي الرموز الأكثر شيوعًا التي قد تواجهها عند استخدام Google Ads API:

رمز gRPC	رمز HTTP	اسم التعداد	الوصف	الإرشادات
0	200	OK	ما مِن خطأ، يشير إلى النجاح.	لا ينطبق
1	499	CANCELLED	تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل العميل.	يعني ذلك عادةً أنّ العميل توقّف عن الانتظار. تحقَّق من المهلات من جهة العميل.
2	500	UNKNOWN	حدث خطأ غير معروف. قد تتوفّر تفاصيل إضافية في رسالة الخطأ أو تفاصيله.	التعامل معها على أنّها خطأ في الخادم يمكن غالبًا إعادة محاولة تنفيذها مع التراجع.
3	400	INVALID_ARGUMENT	حدّد العميل وسيطة غير صالحة. يشير ذلك إلى مشكلة تمنع واجهة برمجة التطبيقات من معالجة الطلب، مثل اسم مورد غير صالح أو قيمة غير صالحة.	خطأ من جهة العميل: راجِع مَعلمات طلبك وتأكَّد من أنّها تستوفي متطلبات واجهة برمجة التطبيقات. تقدّم تفاصيل الخطأ عادةً معلومات حول الوسيط غير الصالح وكيفية إصلاح الطلب باستخدام هذه التفاصيل. لا تعِد المحاولة بدون إصلاح الطلب.
4	504	DEADLINE_EXCEEDED	انتهت المهلة قبل أن تتمكّن العملية من الاكتمال.	خطأ في الخادم: غالبًا ما يكون مؤقتًا. ننصحك بإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
5	404	NOT_FOUND	لم يتم العثور على بعض الكيانات المطلوبة، مثل حملة أو مجموعة إعلانية.	خطأ في العميل: تحقَّق من توفّر الموارد التي تحاول الوصول إليها ومن معرّفاتها. لا تعِد المحاولة بدون تصحيح الخطأ.
6	409	ALREADY_EXISTS	الكيان الذي حاول العميل إنشاءه متوفّر مسبقًا.	خطأ في العميل: تجنَّب إنشاء موارد مكرّرة. تحقَّق مما إذا كان المرجع متوفّرًا قبل محاولة إنشائه.
7	403	PERMISSION_DENIED	ليس لدى المتصل إذن لتنفيذ العملية المحدّدة.	خطأ في العميل: يُرجى التحقّق من المصادقة والأذونات وأدوار المستخدمين لحساب "إعلانات Google". لا تعِد المحاولة بدون حلّ مشكلة الأذونات.
8	429	RESOURCE_EXHAUSTED	إما أنّ المورد قد استُنفد (على سبيل المثال، تجاوزت حصتك)، أو أنّ النظام مثقل.	خطأ في العميل/الخادم: يتطلّب عادةً الانتظار. استخدِم الرقود الأسي الثنائي وربما خفِّض معدّل الطلبات. اطّلِع على حدود واجهات برمجة التطبيقات وحصصها.
9	400	FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها. على سبيل المثال، لم يتم إدخال المعلومات في حقل مطلوب.	خطأ من جهة العميل: الطلب صالح، ولكن الحالة غير صحيحة. راجِع تفاصيل الخطأ لفهم سبب تعذُّر استيفاء الشرط المسبق. لا تعِد المحاولة بدون تصحيح الولاية.
10	409	ABORTED	تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل تعارض المعاملات.	خطأ في الخادم: غالبًا ما يكون من الآمن إعادة المحاولة مع تأخير قصير.
11	400	OUT_OF_RANGE	تمت محاولة تنفيذ العملية بعد انتهاء النطاق الصالح.	خطأ من جهة العميل: صحِّح النطاق أو الفهرس.
12	501	UNIMPLEMENTED	لم يتم تنفيذ العملية أو أنّها غير متاحة في واجهة برمجة التطبيقات.	خطأ في العميل: تحقَّق من إصدار واجهة برمجة التطبيقات والميزات المتاحة. لا تعِد المحاولة.
13	500	INTERNAL	حدث خطأ داخلي. هذا الردّ الجاهز هو ردّ عام وشامل على المشاكل المتعلّقة بالخادم.	خطأ في الخادم: يمكن عادةً إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. إذا استمرّت المشكلة، يُرجى الإبلاغ عنها.
14	503	UNAVAILABLE	هذه الخدمة غير متاحة حاليًا. من المرجّح أنّ هذه الحالة مؤقتة.	حدث خطأ في الخادم: يُنصح بشدة بإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
15	500	DATA_LOSS	ثمة بيانات تالفة أو بيانات مفقودة ويتعذّر استرجاعها.	خطأ في الخادم: نادر. تشير إلى مشكلة خطيرة. لا تعِد المحاولة. إذا استمرّت المشكلة، يُرجى الإبلاغ عنها.
16	401	UNAUTHENTICATED	لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة.	خطأ في العميل: يُرجى التحقّق من رموز المصادقة وبيانات الاعتماد. لا تعِد المحاولة بدون حلّ مشكلة المصادقة.

لمزيد من التفاصيل حول هذه الرموز، يُرجى الرجوع إلى دليل تصميم واجهة برمجة التطبيقات - رموز الأخطاء.

فهم تفاصيل الخطأ

بالإضافة إلى الرمز ذي المستوى الأعلى، توفّر Google Ads API معلومات أكثر تحديدًا عن الأخطاء ضمن الحقل details الخاص بالكائن Status. يحتوي هذا الحقل غالبًا على بروتوكول GoogleAdsFailure، والذي يتضمّن قائمة بعناصر GoogleAdsError فردية.

يحتوي كل عنصر GoogleAdsFailure على ما يلي:

• errors: قائمة بكائنات GoogleAdsError، يشرح كل منها خطأ معيّنًا حدث.
• request_id: معرّف فريد للطلب، وهو مفيد لأغراض تصحيح الأخطاء والدعم.

يوفّر كل عنصر GoogleAdsError ما يلي:

• errorCode: رمز خطأ أكثر تفصيلاً خاصًا بـ Google Ads API، مثل AuthenticationError.NOT_ADS_USER
• ‫message: وصف لخطأ معيّن يمكن قراءته.
• trigger: القيمة التي تسبّبت في حدوث الخطأ، إذا كان ذلك منطبقًا.
• ‫location: يصف هذا الحقل موضع حدوث الخطأ في الطلب، بما في ذلك مسارات الحقول.
• details: تفاصيل إضافية عن الخطأ، مثل أسباب الخطأ غير المنشورة.

مثال على تفاصيل الخطأ

عند تلقّي خطأ، ستتيح لك مكتبة البرامج الوصول إلى هذه التفاصيل. على سبيل المثال، قد يتضمّن الرمز INVALID_ARGUMENT (الرمز 3) تفاصيل GoogleAdsFailure على النحو التالي:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

في هذا المثال، على الرغم من INVALID_ARGUMENT في المستوى الأعلى، تخبرك تفاصيل GoogleAdsFailure أنّ الحقلَين name وdescription هما السبب في المشكلة، كما توضّح لك السبب (REQUIRED وTOO_SHORT على التوالي).

تحديد موقع تفاصيل الخطأ

تعتمد طريقة الوصول إلى تفاصيل الخطأ على ما إذا كنت تستخدم طلبات عادية لواجهة برمجة التطبيقات أو تعذُّر جزئي أو بث مباشر.

طلبات البيانات العادية وطلبات البيانات المتدفقة من واجهة برمجة التطبيقات

عندما يتعذّر تنفيذ طلب إلى واجهة برمجة التطبيقات بدون استخدام ميزة "التعذّر الجزئي"، بما في ذلك طلبات البث، يتم عرض الكائن GoogleAdsFailure كجزء من البيانات الوصفية اللاحقة في عناوين استجابة gRPC. إذا كنت تستخدم REST لإجراء مكالمات عادية، سيتم عرض GoogleAdsFailure في استجابة HTTP. تعرض مكتبات العملاء هذا الخطأ عادةً كاستثناء مع السمة GoogleAdsFailure.

تعذُّر التنفيذ جزئيًا

إذا كنت تستخدم الفشل الجزئي، سيتم عرض أخطاء العمليات الفاشلة في الحقل partial_failure_error من الردّ، وليس في عناوين الردّ. في هذه الحالة، يتم تضمين GoogleAdsFailure ضمن عنصر google.rpc.Status في الردّ.

المهام المجمّعة

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

معرّف الطلب

request-id هي سلسلة فريدة تحدّد طلب واجهة برمجة التطبيقات، وهي ضرورية لتحديد المشاكل وحلّها.

يمكنك العثور على request-id في عدة أماكن:

• GoogleAdsFailure: في حال تعذّر تنفيذ طلب بيانات من واجهة برمجة التطبيقات وتم عرض GoogleAdsFailure، سيتضمّن request_id.
• البيانات الوصفية اللاحقة: لكلّ من الطلبات الناجحة والفاشلة، يتوفّر request-id في البيانات الوصفية اللاحقة لاستجابة gRPC.
• عناوين الاستجابة: بالنسبة إلى الطلبات الناجحة وتلك التي تعذّر تنفيذها، يتوفّر request-id أيضًا في عناوين استجابة gRPC وHTTP، باستثناء طلبات البث الناجحة.
• SearchGoogleAdsStreamResponse: بالنسبة إلى طلبات البث، تحتوي كل رسالة SearchGoogleAdsStreamResponse على حقل request_id.

عند تسجيل الأخطاء أو التواصل مع فريق الدعم، احرص على تضمين request-id للمساعدة في تشخيص المشاكل.

أفضل الممارسات المتعلّقة بمعالجة الأخطاء

لإنشاء تطبيقات مرنة، اتّبِع أفضل الممارسات التالية:

1. فحص تفاصيل الخطأ: عليك دائمًا تحليل الحقل details الخاص بالكائن Status، والبحث تحديدًا عن GoogleAdsFailure. توفّر البيانات التفصيلية في errorCode وmessage وlocation ضمن GoogleAdsError المعلومات الأكثر قابلية للاستخدام في تصحيح الأخطاء وملاحظات المستخدمين.

2. التمييز بين أخطاء العميل وأخطاء الخادم:

   • أخطاء العميل: رموز مثل INVALID_ARGUMENT وNOT_FOUND وPERMISSION_DENIED وFAILED_PRECONDITION وUNAUTHENTICATED تتطلّب هذه الأخطاء إجراء تغييرات على الطلب أو حالة/بيانات اعتماد تطبيقك. لا تعِد محاولة إرسال الطلب بدون حلّ المشكلة.
   • أخطاء الخادم: رموز مثل UNAVAILABLE وINTERNAL وDEADLINE_EXCEEDED وUNKNOWN تشير هذه الرموز إلى حدوث مشكلة مؤقتة في خدمة واجهة برمجة التطبيقات.

3. تنفيذ استراتيجية إعادة المحاولة:

   • متى يجب إعادة المحاولة: أعِد المحاولة فقط في حال حدوث أخطاء مؤقتة في الخادم، مثل UNAVAILABLE وDEADLINE_EXCEEDED وINTERNAL وUNKNOWN وABORTED.
   • الرقود الأسي الثنائي: استخدِم خوارزمية الرقود الأسي الثنائي للانتظار لفترات متزايدة بين عمليات إعادة المحاولة. يساعد ذلك في تجنُّب إرهاق خدمة تعاني من ضغط كبير. على سبيل المثال، الانتظار لمدة ثانية واحدة، ثم ثانيتين، ثم 4 ثوانٍ، وهكذا حتى الوصول إلى الحد الأقصى لعدد محاولات إعادة الإرسال أو إجمالي وقت الانتظار.
   • التفاوت الزمني: أضِف مقدارًا عشوائيًا صغيرًا من "التفاوت الزمني" إلى فترات التأخير لمنع مشكلة "القطيع الصاخب" التي تحدث عندما يعيد العديد من العملاء المحاولة في الوقت نفسه.

4. تسجيل البيانات بدقة: سجِّل استجابة الخطأ الكاملة، بما في ذلك جميع التفاصيل، وخاصةً رقم تعريف الطلب. هذه المعلومات ضرورية لتحديد الأخطاء وإصلاحها ولإبلاغ فريق الدعم في Google بالمشاكل عند الحاجة.

5. تقديم ملاحظات للمستخدمين: استنادًا إلى رموز GoogleAdsError والرسائل المحدّدة، قدِّم ملاحظات واضحة ومفيدة لمستخدمي تطبيقك. على سبيل المثال، بدلاً من قول "حدث خطأ"، يمكنك قول "اسم الحملة مطلوب" أو "لم يتم العثور على رقم تعريف المجموعة الإعلانية المقدَّم".

من خلال اتّباع هذه الإرشادات، يمكنك تشخيص الأخطاء التي تعرضها واجهة برمجة التطبيقات Google Ads API والتعامل معها بفعالية، ما يؤدي إلى إنشاء تطبيقات أكثر استقرارًا وسهولة في الاستخدام.