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