Status

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

  • سهل الاستخدام والفهم لمعظم المستخدمين
  • مرنة بما يكفي لتلبية الاحتياجات غير المتوقعة

ملخص

تحتوي رسالة Status على ثلاثة أجزاء من البيانات: رمز الخطأ، ورسالة الخطأ، وتفاصيل الخطأ. يجب أن يكون رمز الخطأ عبارة عن قيمة تعداد لـ google.rpc.Code ، ولكنه قد يقبل رموز خطأ إضافية إذا لزم الأمر. يجب أن تكون رسالة الخطأ عبارة عن رسالة باللغة الإنجليزية موجهة للمطورين تساعد المطورين على فهم الخطأ وحله . إذا كانت هناك حاجة إلى رسالة خطأ محلية تواجه المستخدم، فضع الرسالة المترجمة في تفاصيل الخطأ أو قم بترجمتها في العميل. قد تحتوي تفاصيل الخطأ الاختيارية على معلومات عشوائية حول الخطأ. توجد مجموعة محددة مسبقًا من أنواع تفاصيل الأخطاء في الحزمة google.rpc والتي يمكن استخدامها لحالات الأخطاء الشائعة.

رسم الخرائط اللغوية

رسالة Status هي التمثيل المنطقي لنموذج الخطأ، ولكنها ليست بالضرورة تنسيق السلك الفعلي. عندما يتم عرض رسالة Status في مكتبات عملاء مختلفة وبروتوكولات سلكية مختلفة، يمكن تعيينها بشكل مختلف. على سبيل المثال، من المحتمل أن يتم تعيينه لبعض الاستثناءات في Java، ولكن من المرجح أن يتم تعيينه لبعض رموز الخطأ في لغة C.

استخدامات اخرى

يمكن استخدام نموذج الخطأ ورسالة Status في مجموعة متنوعة من البيئات، إما مع واجهات برمجة التطبيقات أو بدونها، لتوفير تجربة مطور متسقة عبر بيئات مختلفة.

تتضمن أمثلة استخدامات نموذج الخطأ هذا ما يلي:

  • أخطاء جزئية إذا كانت الخدمة بحاجة إلى إرجاع أخطاء جزئية إلى العميل، فقد تقوم بتضمين Status في الاستجابة العادية للإشارة إلى الأخطاء الجزئية.

  • أخطاء سير العمل. يحتوي سير العمل النموذجي على خطوات متعددة. قد تحتوي كل خطوة على رسالة Status للإبلاغ عن الأخطاء.

  • العمليات الدفعية. إذا كان العميل يستخدم طلبًا مجمعًا واستجابة مجمعة، فيجب استخدام رسالة Status مباشرةً داخل الاستجابة المجمعة، واحدة لكل استجابة فرعية للخطأ.

  • العمليات غير المتزامنة إذا كان استدعاء واجهة برمجة التطبيقات (API) يتضمن نتائج عملية غير متزامنة في استجابتها، فيجب تمثيل حالة تلك العمليات مباشرةً باستخدام رسالة Status .

  • تسجيل. إذا تم تخزين بعض أخطاء واجهة برمجة التطبيقات في السجلات، فيمكن استخدام Status الرسالة مباشرة بعد أي تجريد مطلوب لأسباب تتعلق بالأمان/الخصوصية.

تمثيل جيسون
{
  "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" } .