تحديد المشاكل وحلّها

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

ضمان الاتصال

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

2. يتم تضمين بيانات الاعتماد في طلبك لكي تتمكّن الخدمات من مصادقتك. يجب التعرّف على بنية طلبات Google Ads API وردودها، خاصةً إذا كنت ستتعامل مع الطلبات بدون استخدام مكتبات برامج العميل. يتم توفير تعليمات محدّدة مع كل مكتبة برامج توضّح كيفية تضمين بيانات الاعتماد في ملف الإعداد (يُرجى الرجوع إلى ملف README الخاص بمكتبة البرامج).

3. تأكَّد من استخدام بيانات الاعتماد الصحيحة. يرشدك دليل البدء السريع إلى الخطوات اللازمة للحصول على المجموعة الصحيحة التي تحتاج إليها. على سبيل المثال، يعرض خطأ الرد التالي أنّ المستخدم أرسل بيانات اعتماد مصادقة غير صالحة:

   {
     "error": {
       "code": 401,
       "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. Visit https://developers.google.com/identity/sign-in/web/devconsole-project.",
       "status": "UNAUTHENTICATED",
       "details": [
         {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "Authentication error: 2"
         }
       ]
     }
   }
   

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

تحديد المشكلة

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

{
  "errors": [
    {
      "errorCode": { "fieldMaskError": "FIELD_NOT_FOUND" },
      "message": "The field mask contained an invalid field: 'keyword.match_type'.",
      "location": {
        "fieldPathElements": [
          { "fieldName": "operations", "index": 1 }
        ]
      }
    }
  ]
}

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

البحث عن الخطأ

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

2. إذا لم تذكر مستندات الأخطاء الشائعة الخطأ تحديدًا، يُرجى الرجوع إلى المستندات المرجعية والبحث عن سلسلة الخطأ.

3. يمكنك البحث في قنوات الدعم للوصول إلى مطوّرين آخرين يشاركون تجاربهم مع واجهة برمجة التطبيقات. من المحتمل أنّ مستخدمًا آخر واجه المشكلة نفسها وتمكّن من حلّها.

4. انتقِل إلى مركز مساعدة "إعلانات Google" للحصول على مساعدة في تحديد المشاكل وحلّها المتعلّقة بالتحقّق من الصحة أو حدود الحساب، إذ إنّ Google Ads API تتبع قواعد وقيود منتج "إعلانات Google" الأساسي.

5. في بعض الأحيان، تكون مشاركات المدونة مرجعًا جيدًا عند تحديد المشاكل وحلّها في تطبيقك.

6. إذا واجهت أي أخطاء غير موثّقة، يُرجى التواصل مع فريق الدعم.

بعد البحث عن الخطأ، حان الوقت لتحديد السبب الأساسي.

تحديد السبب

راجِع رسالة الاستثناء لتحديد سبب الخطأ. بعد الاطّلاع على الردّ، تحقَّق من الطلب لمعرفة السبب المحتمل. تتضمّن بعض رسائل الخطأ في Google Ads API الرمز fieldPathElements في الحقل location ضمن GoogleAdsError، ما يشير إلى موضع حدوث الخطأ في الطلب. على سبيل المثال:

{
  "errors": [
    {
      "errorCode": {"criterionError": "CANNOT_ADD_CRITERIA_TYPE"},
      "message": "Criteria type can not be targeted.",
      "trigger": { "stringValue": "" },
      "location": {
        "fieldPathElements": [
          { "fieldName": "operations", "index": 0 },
          { "fieldName": "create" },
          { "fieldName": "keyword" }
        ]
      }
    }
  ]
}

عند تحديد المشاكل وحلّها، قد تجد أنّ تطبيقك يقدّم معلومات غير صحيحة إلى واجهة برمجة التطبيقات. ننصح بشدة باستخدام أداة تصحيح الأخطاء في بيئة التطوير المتكاملة (IDE) لضبط نقاط التوقف، وتتبُّع التعليمات البرمجية سطرًا بسطر، وفحص حمولات الطلبات التي تم إنشاؤها قبل إرسالها.

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

كيفية الحصول على مساعدة

قد لا يكون من الممكن دائمًا تحديد المشكلة وحلّها بنفسك. يمكنك التواصل مع فريق الدعم للحصول على المساعدة.

حاوِل تضمين أكبر قدر ممكن من المعلومات في طلبات البحث. تشمل العناصر المقترَحة ما يلي:

• طلب JSON واستجابة JSON تم تنظيفهما احرص على إزالة المعلومات الحسّاسة، مثل رمز الدخول ببروتوكول OAuth، والرمز المميز لإعادة التحميل، والرمز المميز للمطوِّر (إذا كان لا يزال مضمّنًا في عناوين الطلبات القديمة) وأرقام تعريف العملاء.
• مقتطفات الرموز البرمجية إذا كنت تواجه مشكلة خاصة بلغة معيّنة أو تطلب المساعدة في استخدام واجهة برمجة التطبيقات، أدرِج مقتطفًا من الرمز البرمجي للمساعدة في توضيح ما تفعله.
• request-id: يتيح ذلك لأعضاء فريق علاقات المطوّرين في Google العثور على طلبك إذا تم تقديمه في بيئة التشغيل الفعلي. ننصحك بتسجيل request-id المضمّنة في عناوين الاستجابة أو الاستثناءات التي تتضمّن أخطاء الاستجابة، بالإضافة إلى توفير سياق أكثر من request-id وحدها.
• يمكن أن تكون المعلومات الإضافية، مثل وقت التشغيل أو إصدار المترجم والمنصة، مفيدة أيضًا عند تحديد المشاكل وحلّها.

حلّ المشكلة

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

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

بعد حلّ هذه المشكلة، هل لاحظت أي طرق لتحسين الرمز البرمجي لتجنُّبها في المقام الأول؟

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