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