أنواع الأخطاء

تم تصنيف الأخطاء ضمن الفئات العامة التالية:

• المصادقة
• قابل لإعادة المحاولة
• التحقّق من الصحة
• مرتبط بالمزامنة

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

أخطاء المصادقة

تشير المصادقة إلى ما إذا تم منح تطبيقك إذنًا من قِبل أحد المستخدمين للوصول إلى إعلانات Google نيابةً عنه. تتم إدارة المصادقة من خلال بيانات الاعتماد التي تم إنشاؤها بواسطة تدفق OAuth2.

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

أخطاء قابلة لإعادة المحاولة

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

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

بالنسبة إلى الطلبات التي يتم بدؤها في الخلفية، يجب أن يُعيد تطبيقك تلقائيًا محاولة معالجة الطلب بحد أقصى لعدد مرات إعادة المحاولة يصل إلى الحد الأقصى.

وعند إعادة محاولة الطلبات، يمكنك استخدام سياسة التراجع الأسي. على سبيل المثال، في حالة التوقف المؤقت لأول مرة قبل 5 ثوانٍ من إعادة المحاولة الأولى، يمكنك التوقف مؤقتًا بعد 10 ثوانٍ من الثانية و20 ثانية بعد المحاولة الثالثة. يساعد التراجع الأسي على ضمان عدم استدعاء واجهة برمجة التطبيقات بشكل صارم للغاية.

أخطاء التحقق من الصحة

تشير أخطاء التحقق من صحة البيانات إلى أن الإدخال في إحدى العمليات لم يكن مقبولاً. على سبيل المثال، PolicyViolationError وDateError وDateRangeError وStringLengthError وUrlFieldError.

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

الأخطاء المتعلقة بالمزامنة

تحتفظ العديد من تطبيقات إعلانات Google بقاعدة بيانات محلية لتخزين كائنات إعلانات Google. من التحديات التي تواجه هذا الأسلوب هو أن قاعدة البيانات المحلية قد لا تكون متزامنة مع العناصر الفعلية في إعلانات Google. على سبيل المثال، قد يحذف أحد المستخدمين مجموعة إعلانية مباشرةً من "إعلانات Google"، إلا أن التطبيق وقاعدة البيانات المحلية لا يدركان هذا التغيير ويستمران في إصدار طلبات بيانات من واجهة برمجة التطبيقات كما لو كانت المجموعة الإعلانية موجودة من قبل. يمكن أن تظهر مشاكل المزامنة هذه في شكل مجموعة متنوعة من الأخطاء مثل DUPLICATE_CAMPAIGN_NAME وDUPLICATE_ADGROUP_NAME AD_NOT_UNDER_ADGROUP وCANNOT_OPERATE_ON_REMOVED_ADGROUPAD وغيرها الكثير.

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

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