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

يشرح هذا الدليل كيفية تعامل 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 ما يلي:

• ‫error_code: رسالة خطأ أكثر تفصيلاً وخاصة بواجهة Google Ads API ErrorCode (الأخطاء الشائعة)، مثل AuthenticationError.NOT_ADS_USER.
• ‫message: وصف للخطأ المحدّد يمكن لشخص عادي قراءته
• ‫trigger: السمة Value التي تسبّبت في حدوث الخطأ، إن وُجدت
• ‫location: ErrorLocation يصف مكان حدوث الخطأ في الطلب، بما في ذلك مسارات الحقول.
• details: ErrorDetails إضافية، مثل أسباب الأخطاء غير المنشورة

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

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

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

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

تحديد تفاصيل الخطأ

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

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

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

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

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

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

بالنسبة إلى المعالجة على دفعات، يمكن العثور على أخطاء العمليات الفردية من خلال طلب BatchJobService.ListBatchJobResults بعد اكتمال المهمة. ستتضمّن كل نتيجة عملية حقل 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. توفّر البيانات الدقيقة حول error_code و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 والتعامل معها بفعالية، ما يؤدي إلى إنشاء تطبيقات أكثر استقرارًا وسهولة في الاستخدام.