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

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

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

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

• تقدّم صفحة الأخطاء الشائعة مزيدًا من التفاصيل حول خطأ معيّن.
• google.rpc.Status للحصول على تفاصيل حول نموذج الخطأ المنطقي الذي تستخدمه واجهة برمجة التطبيقات

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

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