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

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

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

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

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

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