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

لقد صنّفنا الأخطاء إلى الفئات الواسعة التالية:

• المصادقة
• يمكن إعادة المحاولة
• التحقّق من الصحة
• ذو صلة بالمزامنة

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

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

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