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

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

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

بنية الخطأ

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

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

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

• error_code: رمز خطأ معيّن يوضّح نوع الخطأ، مثل AuthenticationError.NOT_ADS_USER.
• ‫message: وصف مفهوم لسبب حدوث الخطأ.
• trigger: القيمة التي تسبّبت في الخطأ، مثل "1234".
• location: تفاصيل حول الجزء الذي تسبّب في حدوث الخطأ في الطلب، مثل اسم حقل معيّن

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

مثال على الخطأ

في ما يلي مثال على شكل الخطأ بتنسيق JSON. يشير هذا الخطأ إلى أنّ الحقل name الخاص بـ ad_group في الفهرس 0 غير مضمَّن في الطلب.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

كيفية التعامل مع الأخطاء

في حال ظهور خطأ، إليك الخطوات التي يجب اتّخاذها:

1. فحص قائمة errors: انظر إلى كل GoogleAdsError في عنصر GoogleAdsFailure. سيخبرك الرمز error_code والرمز message بالمشكلة.
2. التحقّق من location: يمكن أن يساعدك حقل location في تحديد المكان الذي حدثت فيه المشكلة في طلبك.
3. الرجوع إلى المستندات: بالنسبة إلى رموز الخطأ المحدّدة، يمكنك الاطّلاع على صفحة الأخطاء الشائعة أو مرجع رموز الخطأ الكامل للحصول على مزيد من التفاصيل حول الخطأ وكيفية إصلاحه.
4. تعديل طلبك: استنادًا إلى رسالة الخطأ، صحِّح طلب البيانات من واجهة برمجة التطبيقات. على سبيل المثال، إذا رأيت REQUIRED_FIELD_MISSING، تأكَّد من توفير هذا الحقل في طلبك.
5. تسجيل request_id: إذا لم تتمكّن من معرفة كيفية حلّ الخطأ وكنت بحاجة إلى التواصل مع فريق الدعم من خلال المنتدى، عليك تضمين request_id. يساعد هذا المعرّف مهندسي Google في التحقيق في مشكلتك.

الخطوات التالية

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