يمكن أن تحدث الأخطاء بسبب إعداد بيئة غير صحيح، أو خطأ في البرنامج، أو إدخال غير صالح من المستخدم. بغض النظر عن المصدر، ستحتاج إلى تحديد المشكلة وحلّها، وإما إصلاح الرمز أو إضافة منطق للتعامل مع خطأ المستخدم. يتناول هذا الدليل بعض أفضل الممارسات عند تحديد المشاكل وحلّها في 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" الأساسي.
منشورات المدوّنة ستكون في بعض الأحيان مرجعًا جيدًا عند تحديد المشاكل وحلّها في تطبيقك.
إذا واجهت أي أخطاء غير موثَّقة، يُرجى التواصل مع فريق الدعم.
بعد البحث في الخطأ، يحين وقت تحديد السبب الأساسي.
تحديد السبب
تحقَّق من رسالة الاستثناء لتحديد سبب الخطأ. بعد الاطّلاع على الردّ، تحقَّق من الطلب لمعرفة السبب المحتمل. تتضمّن بعض رسائل الخطأ في 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 العثور على طلبك إذا تم إرساله إلى بيئة التشغيل الفعلي. ننصحك بتسجيلrequest-idالمضمّن في عناوين الاستجابة أو الاستثناءات التي تتضمّن أخطاء الاستجابة، بالإضافة إلى سياق أكثر منrequest-idوحده.- يمكن أن تكون المعلومات الإضافية، مثل وقت التشغيل أو إصدار المترجم والنظام الأساسي، مفيدة أيضًا عند تحديد المشاكل وحلّها.
حلّ المشكلة
بعد أن حدّدت المشكلة وتوصّلت إلى حلّ، حان الوقت لإجراء التغيير واختبار الإصلاح على حساب تجريبي (مفضّل) أو حساب إنتاج (إذا كان الخطأ ينطبق فقط على البيانات في حساب إنتاج معيّن).
الخطوات التالية
بعد أن حللت هذه المشكلة، هل لاحظت أي طرق لتحسين الرمز لتجنب ذلك في المقام الأول؟
يساعد إنشاء مجموعة جيدة من اختبارات الوحدات في تحسين جودة الرمز البرمجي وموثوقيته بشكل كبير. كما أنه يسرع عملية اختبار التغييرات الجديدة لضمان عدم كسر الوظائف السابقة. تُعدّ الاستراتيجية الجيدة لمعالجة الأخطاء أيضًا مفتاحًا لعرض جميع البيانات اللازمة لتحديد المشاكل وحلّها.