Status

يحدّد النوع 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

number

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

message

string

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

details[]

object

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

كائن يحتوي على حقول من نوع عشوائي يحتوي الحقل الإضافي "@type" على معرف موارد منتظم (URI) يحدّد النوع. مثال: { "id": 1234, "@type": "types.example.com/standard/id" }