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

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

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

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

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

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

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

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

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

بالإضافة إلى الرمز ذي المستوى الأعلى، توفّر Google Ads API معلومات أكثر تحديدًا عن الخطأ ضمن الحقل details الخاص بالكائن Status. يحتوي هذا الحقل غالبًا على GoogleAdsFailure proto، والذي يتضمّن قائمة بعناصر 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، يتم عرض أخطاء العمليات التي تعذّر تنفيذها في الحقل 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 والتعامل معها بفعالية، ما يؤدي إلى إنشاء تطبيقات أكثر استقرارًا وسهولة في الاستخدام.