Package google.rpc

المؤشر

الرمز

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

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

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

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

تعيين HTTP: 200 OK

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 Too Many Requests

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 Not Implemented

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

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