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

لقد صنّفنا الأخطاء في الفئات العريضة التالية:

  • المصادقة
  • الأخطاء التي يمكن إعادة المحاولة فيها
  • التحقق من صحة البيانات
  • الأخطاء المتعلّقة بالمزامنة

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

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

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

التالي
التعرّف على أخطاء واجهة برمجة التطبيقات