Package google.rpc

الفهرس

الرمز

رموز الخطأ الأساسية لواجهات برمجة تطبيقات gRPC

في بعض الأحيان قد تنطبق رموز خطأ متعددة. من المفترض أن تعرض الخدمات رمز الخطأ الأكثر تحديدًا الذي ينطبق. على سبيل المثال، يمكنك تفضيل OUT_OF_RANGE على FAILED_PRECONDITION إذا تم تطبيق كلا الرمزين. بالمثل، يُرجى تفضيل NOT_FOUND أو ALREADY_EXISTS على FAILED_PRECONDITION.

عمليات التعداد
OK

ليس خطأ؛ تم إرجاعها بنجاح.

تعيين HTTP: 200 حسنًا
CANCELLED

تم إلغاء العملية، وعادةً ما يكون المتصل بها.

تعيين HTTP: طلب مغلق من عميل 499
UNKNOWN

حدث خطأ غير معروف. على سبيل المثال، قد يظهر هذا الخطأ عندما تنتمي قيمة Status تم استلامها من مساحة عنوان أخرى إلى مساحة خطأ غير معروفة في مساحة العنوان هذه. قد يتم أيضًا تحويل الأخطاء التي تُحدثها واجهات برمجة التطبيقات والتي لا تعرض معلومات كافية عن الخطأ إلى هذا الخطأ.

تعيين HTTP: خطأ في الخادم الداخلي 500
INVALID_ARGUMENT

حدَّد العميل وسيطة غير صالحة. لاحظ أن هذا يختلف عن FAILED_PRECONDITION. تشير السمة INVALID_ARGUMENT إلى الوسيطات المسببة للمشاكل بغض النظر عن حالة النظام (مثل اسم ملف مكتوب بشكلٍ غير صحيح).

تعيين HTTP: 400 طلب غير صالح
DEADLINE_EXCEEDED

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

تعيين HTTP: مهلة البوابة 504
NOT_FOUND

لم يتم العثور على بعض العناصر المطلوبة (مثل ملف أو دليل).

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

تعيين HTTP: 404 لم يتم العثور على الصفحة
ALREADY_EXISTS

الكيان الذي حاول العميل إنشاءه (مثل ملف أو دليل) موجود من قبل.

تعيين HTTP: تعارض 409
PERMISSION_DENIED

لا يملك المتصل إذنًا لتنفيذ العملية المحددة. يجب عدم استخدام PERMISSION_DENIED لحالات الرفض الناتجة عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED بدلاً من ذلك لمعالجة هذه الأخطاء). يجب عدم استخدام PERMISSION_DENIED إذا تعذّر تحديد هوية المتصل (استخدِم UNAUTHENTICATED بدلاً من ذلك للإشارة إلى هذه الأخطاء). لا يشير رمز الخطأ هذا إلى أنّ الطلب صالح أو أنّ الكيان المطلوب موجود أو يستوفي شروطًا مسبقة أخرى.

تعيين HTTP: 403 محظور
UNAUTHENTICATED

لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة للعملية.

تعيين HTTP: 401 غير مصرح به
RESOURCE_EXHAUSTED

تم استنفاد بعض الموارد، ربما الحصة لكل مستخدم، أو ربما نفدت مساحة نظام الملفات بالكامل.

تعيين HTTP: 429 طلبات كثيرة جدًا
FAILED_PRECONDITION

تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذ العملية. على سبيل المثال، يكون الدليل المطلوب حذفه غير فارغ، ويتم تطبيق عملية rmdir على غير دليل، وما إلى ذلك.

يمكن لمنفِّذي الخدمة استخدام الإرشادات التالية للاختيار بين FAILED_PRECONDITION وABORTED وUNAVAILABLE: (أ) استخدِم UNAVAILABLE إذا كان بإمكان العميل إعادة محاولة الاتصال التي تعذّر تنفيذها فقط. (ب) استخدِم ABORTED إذا كان على العميل إعادة المحاولة على مستوى أعلى. على سبيل المثال، عند تعذُّر الاختبار والإعداد المحدّدَين من قِبل العميل، يشير ذلك إلى أنّ العميل يجب أن يعيد تشغيل تسلسل قراءة وتعديل والكتابة. (ج) استخدِم FAILED_PRECONDITION إذا كان يجب على العميل عدم إعادة المحاولة حتى يتم إصلاح حالة النظام صراحةً. على سبيل المثال، إذا تعذّر تنفيذ الأمر "rmdir" لأنّ الدليل غير فارغ، يجب عرض FAILED_PRECONDITION لأنّه يجب على العميل عدم إعادة المحاولة ما لم يتم حذف الملفات من الدليل.

تعيين HTTP: 400 طلب غير صالح
ABORTED

تم إلغاء العملية، عادةً بسبب مشكلة في التزامن، مثل تعذُّر التحقّق من جهاز التسلسل أو إلغاء المعاملة.

يمكنك الاطّلاع على الإرشادات أعلاه للاختيار بين FAILED_PRECONDITION وABORTED وUNAVAILABLE.

تعيين HTTP: تعارض 409
OUT_OF_RANGE

تمت محاولة العملية بعد تجاوز النطاق الصالح. على سبيل المثال، التقديم/الترجيع أو القراءة في نهاية الملف

على عكس INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة يمكن حلّها في حال تغيّرت حالة النظام. على سبيل المثال، سينشئ نظام ملفات 32 بت INVALID_ARGUMENT إذا تمت مطالبتك بالقراءة بقيمة إزاحة ليست ضمن النطاق [0,2^32-1]، ولكن سينشئ OUT_OF_RANGE إذا طُلب منك قراءته من إزاحة تتجاوز حجم الملف الحالي.

هناك بعض التداخل إلى حد ما بين FAILED_PRECONDITION وOUT_OF_RANGE. وننصح باستخدام الخطأ OUT_OF_RANGE (الخطأ الأكثر تحديدًا) عند تطبيقه حتى يتمكن المتصلون الذين يجرون تكرارًا في مساحة ما من البحث بسهولة عن خطأ OUT_OF_RANGE لرصد الخطأ عند انتهاء العملية.

تعيين HTTP: 400 طلب غير صالح
UNIMPLEMENTED

لم يتم تنفيذ العملية أو أنها غير متاحة/مفعّلة في هذه الخدمة.

تعيين HTTP: لم يتم تنفيذ 501
INTERNAL

أخطاء داخلية. وهذا يعني أنّ بعض القيم الثابتة التي توقّعها النظام الأساسي قد تعطلت. يتم الاحتفاظ برمز الخطأ هذا للأخطاء الجسيمة.

تعيين HTTP: خطأ في الخادم الداخلي 500
UNAVAILABLE

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

يمكنك الاطّلاع على الإرشادات أعلاه للاختيار بين FAILED_PRECONDITION وABORTED وUNAVAILABLE.

تعيين HTTP: الخدمة 503 غير متاحة
DATA_LOSS

تلف أو فقدان بيانات غير قابل للإصلاح.

تعيين HTTP: خطأ في الخادم الداخلي 500

الحالة

يحدد النوع Status نموذج خطأ منطقي مناسب لبيئات البرمجة المختلفة، بما في ذلك واجهات برمجة تطبيقات REST وواجهات برمجة التطبيقات RPC. ويتم استخدامه من قِبل gRPC. تحتوي كل رسالة Status على ثلاث أجزاء من البيانات: رمز الخطأ ورسالة الخطأ وتفاصيل الخطأ.

يمكنك معرفة المزيد حول نموذج الخطأ هذا وكيفية التعامل معه في دليل تصميم واجهة برمجة التطبيقات.

الحقول
code

int32

رمز الحالة، الذي يجب أن يكون قيمة تعداد google.rpc.Code
message

string

رسالة خطأ موجّهة للمطوّر، ويجب أن تكون باللغة الإنجليزية. يجب ترجمة أي رسالة خطأ تظهر للمستخدمين وإرسالها في حقل google.rpc.Status.details أو ترجمتها من خلال البرنامج.
details[]

Any

قائمة بالرسائل التي تتضمن تفاصيل الخطأ. هناك مجموعة شائعة من أنواع الرسائل التي يمكن أن تستخدمها واجهات برمجة التطبيقات.