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

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

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

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

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

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

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

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

في السياق نفسه، إذا كان مشروعك على Google Cloud يتضمّن مستوى الوصول التجريبي فقط وحاول إرسال طلبات إلى حساب نهائي (غير تجريبي)، ستعرض واجهة برمجة التطبيقات الرمز AuthorizationError الذي تعتمد قيمة التعداد الخاصة به على إصدار واجهة برمجة التطبيقات:

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

يمكن أن تشير بعض الأخطاء، مثل TRANSIENT_ERROR أو INTERNAL_ERROR، إلى مشكلة مؤقتة يمكن حلّها من خلال إعادة محاولة الطلب بعد توقّف قصير.

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

بالنسبة إلى الطلبات التي يتم إرسالها من الخلفية، يجب أن يعيد تطبيقك تلقائيًا محاولة إرسال الطلب بما يصل إلى الحد الأقصى لعدد المحاولات.

عند إعادة محاولة إرسال الطلبات، استخدِم سياسة الرقود الأسي الثنائي مع تشويش عشوائي. على سبيل المثال، إذا أوقفت مؤقتًا لمدة 5 ثوانٍ قبل إعادة المحاولة الأولى، يمكنك إيقافها مؤقتًا لمدة 10 ثوانٍ بعد إعادة المحاولة الثانية و20 ثانية بعد إعادة المحاولة الثالثة، مع إضافة تأخير عشوائي صغير إلى كل فاصل زمني لمنع الارتفاعات المفاجئة في عمليات إعادة المحاولة المتزامنة. تساعد ميزة "التراجع الأسي" في ضمان عدم إرسال طلبات إلى واجهة برمجة التطبيقات بشكل مفرط. إذا استمرّ الخطأ بعد استنفاد محاولات إعادة التشغيل، سجِّل request-id من الردّ لتحديد المشاكل وحلّها.

أخطاء التحقق من الصحة

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

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