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

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

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

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

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

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

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

إنّ السبب الأكثر شيوعًا لظهور خطأ في المصادقة بسبب عوامل خارجة عن إرادتك هو أنّ المستخدم الذي تمّت المصادقة عليه ألغى الإذن الذي منحه لتطبيقك بالتصرّف نيابةً عنه. على سبيل المثال، إذا كان تطبيقك يدير حسابات منفصلة على "إعلانات Google" لعملاء مستقلين ويُثبِّت هويته بشكل منفصل لكل عميل عند إدارة حسابه، يمكن للعميل إبطال إذن وصول تطبيقك في أي وقت. استنادًا إلى وقت إبطال إذن الوصول، قد تعرض واجهة برمجة التطبيقات مباشرةً خطأ AuthenticationError.OAUTH_TOKEN_REVOKED، أو قد تُعرِض مكتبات العملاء استثناءً لإبطال الرمز المميّز. وفي كلتا الحالتَين، إذا كان تطبيقك يتضمّن واجهة مستخدم للعملاء، قد يطلب منهم إعادة تشغيل عملية OAuth2 لإعادة منح تطبيقك permissão للقيام بالإجراءات نيابةً عنهم.

الأخطاء التي يمكن إعادة محاولة حلّها

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