يمكن أن تنتج الأخطاء عن إعداد غير صحيح للبيئة أو خطأ في برنامجك أو إدخال غير صالح من المستخدم. بغض النظر عن المصدر، عليك تحديد المشكلة وحلّها، إما عن طريق إصلاح الرمز أو إضافة منطق للتعامل مع خطأ المستخدم. يناقش هذا الدليل بعض أفضل الممارسات عند تحديد المشاكل وحلّها في Google Ads API.
ضمان الاتصال
تأكَّد من إمكانية الوصول إلى Google Ads API ومن إعدادها بشكل صحيح. إذا كانت استجابتك تعرض أي أخطاء HTTP، تأكَّد من معالجتها بعناية ومن أنّك تصل إلى الخدمات التي تنوي استخدامها من الرمز.
يتم تضمين بيانات الاعتماد في طلبك لكي تتمكّن الخدمات من مصادقتك. تعرَّف على بنية طلبات بيانات من واجهة برمجة التطبيقات واستجاباتها في Google Ads API، خاصةً إذا كنت ستتعامل مع الطلبات بدون استخدام مكتبات العميل. يتم شحن كل مكتبة عميل مع تعليمات محدّدة حول كيفية تضمين بيانات الاعتماد في ملف الإعداد (راجِع ملف README الخاص بمكتبة العميل).
تأكَّد من أنّك تستخدم بيانات الاعتماد الصحيحة. يرشدك دليل البدء السريع خلال عملية الحصول على المجموعة الصحيحة التي تحتاج إليها. على سبيل المثال، يوضّح فشل الاستجابة التالي أنّ المستخدم أرسل بيانات اعتماد غير صالحة للمصادقة:
{ "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 }
]
}
}
]
}
تُنشئ جميع مكتبات العملاء استثناءات تتضمّن الأخطاء في الاستجابة. إنّ رصد هذه الاستثناءات وطباعة الرسائل في سجلّ أو شاشة تحديد المشاكل وحلّها هي طريقة رائعة للبدء. إنّ دمج هذه المعلومات مع الأحداث الأخرى التي تم تسجيلها في تطبيقك يقدّم نظرة عامة جيدة على ما قد يؤدي إلى حدوث المشكلة. بعد تحديد الخطأ في السجلّات، عليك معرفة معناه.
البحث عن الخطأ
راجِع مستندات الأخطاء الشائعة التي تغطي الأخطاء الأكثر شيوعًا. تصف هذه المستندات رسالة الخطأ ومراجع واجهة برمجة التطبيقات ذات الصلة وكيفية تجنُّب الخطأ أو التعامل معه.
إذا لم تذكر مستندات الأخطاء الشائعة الخطأ تحديدًا، راجِع مستندات المرجع وابحث عن سلسلة الخطأ.
ابحث في قنوات الدعم للوصول إلى مطوّرين آخرين يشاركون تجاربهم مع واجهة برمجة التطبيقات. من المحتمل أنّ شخصًا آخر قد واجه المشكلة التي تواجهها وحلّها.
انتقِل إلى مركز مساعدة "إعلانات Google" للحصول على مساعدة في تحديد المشاكل وحلّها المتعلّقة بالتحقّق من الصحة أو حدود الحساب، إذ إنّ Google Ads API تكتسب قواعد وقيود منتج "إعلانات Google" الأساسي.
مشاركات المدونة في بعض الأحيان، ستكون مرجعًا جيدًا عند تحديد المشاكل وحلّها في تطبيقك.
إذا واجهت أي أخطاء غير موثّقة، تواصَل مع فريق الدعم support.
بعد البحث عن الخطأ، حان الوقت لتحديد السبب الأساسي.
تحديد السبب
راجِع رسالة الاستثناء لتحديد سبب الخطأ. بعد الاطّلاع على الاستجابة، ابحث في الطلب عن سبب محتمل. تتضمّن بعض رسائل الخطأ في 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 بعد إزالة المعلومات الحساسة. تأكَّد من إزالة المعلومات الحساسة، مثل رمز الوصول ورمز إعادة التحميل ورموز تعريف العملاء ببروتوكول OAuth.
- مقتطفات الرمز. إذا كنت تواجه مشكلة خاصة بلغة معيّنة أو تطلب مساعدة في استخدام واجهة برمجة التطبيقات، أدرِج مقتطفًا من الرمز للمساعدة في توضيح ما تفعله.
request-id: يتيح هذا لأعضاء فريق علاقات Google Developers تحديد موقع طلبك إذا تم إرساله إلى بيئة التشغيل الفعلي. ننصح بتسجيلrequest-idالمضمّن في عناوين الاستجابة أو الاستثناءات التي تتضمّن أخطاء الاستجابة، بالإضافة إلى سياق أكثر منrequest-idوحده.- يمكن أن تكون المعلومات الإضافية، مثل وقت التشغيل أو إصدار المحلّل الأساسي والمنصة، مفيدة أيضًا عند تحديد المشاكل وحلّها.
حلّ المشكلة
بعد تحديد المشكلة والتوصل إلى حلّ، حان الوقت لإجراء التغيير واختبار الإصلاح على حساب تجريبي (يُفضّل ذلك) أو حساب إنتاج (إذا كان الخطأ ينطبق فقط على البيانات في حساب إنتاج معيّن).
الخطوات التالية
بعد حلّ هذه المشكلة، هل لاحظت أي طرق لتحسين الرمز لتجنُّب حدوثها في المقام الأول؟
يساعد إنشاء مجموعة جيدة من اختبارات الوحدات في تحسين جودة الرمز وموثوقيته بشكل كبير. كما يسرّع عملية اختبار التغييرات الجديدة لضمان عدم تعطيل الوظائف السابقة. إنّ وضع استراتيجية جيدة للتعامل مع الأخطاء هو أيضًا أمر أساسي في عرض جميع البيانات اللازمة لتحديد المشاكل وحلّها.