يحدّد النوع Status
نموذج خطأ منطقي مناسبًا لبيئات البرمجة المختلفة، بما في ذلك واجهات برمجة تطبيقات REST وواجهات برمجة تطبيقات RPC. وتُستخدَم من قِبل gRPC. تم تصميم نموذج الخطأ ليكون:
- يسهل استخدامها وفهمها لمعظم المستخدمين
- المرونة الكافية لتلبية الاحتياجات غير المتوقعة
نظرة عامة
تحتوي رسالة Status
على ثلاث بيانات: رمز الخطأ ورسالة الخطأ وتفاصيل الخطأ. يجب أن يكون رمز الخطأ عبارة عن قيمة تعداد بقيمة google.rpc.Code
، ولكن قد يقبل رموز خطأ إضافية إذا لزم الأمر. يجب أن تكون رسالة الخطأ موجّهة باللغة الإنجليزية موجّهة للمطوّرين، ما يساعدهم على فهم الخطأ وحلّه. إذا كانت هناك حاجة إلى رسالة خطأ مترجمة موجّهة للمستخدمين، يُرجى وضع الرسالة المترجَمة في تفاصيل الخطأ أو ترجمتها في البرنامج. قد تحتوي التفاصيل الاختيارية للخطأ على معلومات عشوائية حول الخطأ. هناك مجموعة محدّدة مسبقًا من أنواع تفاصيل الأخطاء في الحزمة google.rpc
يمكن استخدامها لحالات الأخطاء الشائعة.
تحديد اللغة
تمثّل رسالة Status
التمثيل المنطقي لنموذج الخطأ، ولكنها ليست بالضرورة تنسيق السلك الفعلي. عندما تظهر رسالة Status
في مكتبات عملاء مختلفة وبروتوكولات سلكية مختلفة، يمكن ربطها بشكل مختلف. على سبيل المثال، من المحتمل أن يتم تعيينه لبعض الاستثناءات في Java، ولكن على الأرجح يتم ربطه ببعض رموز الخطأ في C.
استخدامات أخرى
يمكن استخدام نموذج الخطأ ورسالة Status
في بيئات مختلفة، إمّا باستخدام واجهات برمجة التطبيقات أو بدونها، وذلك لتوفير تجربة متّسقة للمطوّرين على مستوى البيئات المختلفة.
تشمل أمثلة استخدامات نموذج الخطأ هذا ما يلي:
حدثت أخطاء جزئية. إذا كانت إحدى الخدمات تحتاج إلى عرض أخطاء جزئية للعميل، قد تضمّن
Status
في الردّ العادي للإشارة إلى الأخطاء الجزئية.أخطاء في سير العمل يتضمن سير العمل المعتاد خطوات متعددة. وقد تحتوي كل خطوة على رسالة
Status
للإبلاغ عن الأخطاء.العمليات المجمّعة. إذا كان العميل يستخدم الطلب المجمّع والاستجابة المجمّعة، يجب استخدام الرسالة
Status
مباشرةً داخل الرد المجمّع، مع تضمين رسالة واحدة لكل رد فرعي عن الخطأ.العمليات غير المتزامنة. إذا تضمّن طلب بيانات من واجهة برمجة التطبيقات نتائج عملية غير متزامنة في الردّ، يجب تمثيل حالة تلك العمليات مباشرةً باستخدام رسالة
Status
.التسجيل إذا تم تخزين بعض أخطاء واجهة برمجة التطبيقات في السجلّات، يمكن استخدام الرسالة
Status
مباشرةً بعد أي عملية إزالة مطلوبة لأسباب تتعلّق بالأمان أو الخصوصية.
تمثيل JSON | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
الحقول | |
---|---|
code |
رمز الحالة، الذي يجب أن يكون قيمة تعداد بقيمة |
message |
رسالة خطأ مواجهة للمطوِّر، ويجب أن تكون باللغة الإنجليزية يجب ترجمة أي رسالة خطأ تظهر للمستخدم وإرسالها في الحقل |
details[] |
قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. وهناك مجموعة شائعة من أنواع الرسائل التي يمكن لواجهات برمجة التطبيقات استخدامها. كائن يحتوي على حقول من نوع عشوائي يحتوي الحقل الإضافي |