Status

نوع Status یک مدل خطای منطقی را تعریف می کند که برای محیط های برنامه نویسی مختلف، از جمله REST API و RPC API مناسب است. توسط gRPC استفاده می شود. مدل خطا به صورت زیر طراحی شده است:

  • استفاده و درک برای اکثر کاربران ساده است
  • به اندازه کافی انعطاف پذیر است تا نیازهای غیرمنتظره را برآورده کند

بررسی اجمالی

پیام Status شامل سه داده است: کد خطا، پیام خطا و جزئیات خطا. کد خطا باید یک مقدار enum google.rpc.Code باشد، اما در صورت نیاز ممکن است کدهای خطای اضافی را بپذیرد. پیام خطا باید یک پیام انگلیسی رو به توسعه‌دهنده باشد که به توسعه‌دهندگان کمک می‌کند تا خطا را درک کرده و برطرف کنند . اگر به یک پیام خطای محلی شده برای کاربر نیاز است، پیام محلی شده را در جزئیات خطا قرار دهید یا آن را در کلاینت بومی سازی کنید. جزئیات خطای اختیاری ممکن است حاوی اطلاعات دلخواه در مورد خطا باشد. مجموعه ای از پیش تعریف شده از انواع جزئیات خطا در بسته google.rpc وجود دارد که می تواند برای شرایط خطای رایج استفاده شود.

نقشه برداری زبان

پیام Status نمایش منطقی مدل خطا است، اما لزوماً قالب واقعی سیم نیست. هنگامی که پیام Status در کتابخانه‌های کلاینت‌های مختلف و پروتکل‌های سیمی مختلف نمایش داده می‌شود، می‌توان آن را به‌صورت متفاوتی نگاشت کرد. به عنوان مثال، احتمالاً به برخی استثناها در جاوا نگاشت می شود، اما به احتمال زیاد به برخی از کدهای خطا در C نگاشت می شود.

استفاده های دیگر

مدل خطا و پیام Status را می‌توان در محیط‌های مختلف، با یا بدون API، برای ارائه یک تجربه توسعه‌دهنده سازگار در محیط‌های مختلف استفاده کرد.

نمونه های استفاده از این مدل خطا عبارتند از:

  • خطاهای جزئی اگر یک سرویس نیاز به بازگرداندن خطاهای جزئی به مشتری داشته باشد، ممکن است Status را در پاسخ عادی برای نشان دادن خطاهای جزئی جاسازی کند.

  • خطاهای گردش کار یک گردش کار معمولی چندین مرحله دارد. هر مرحله ممکن است یک پیام Status برای گزارش خطا داشته باشد.

  • عملیات دسته ای اگر مشتری از درخواست دسته ای و پاسخ دسته ای استفاده می کند، پیام Status باید مستقیماً در داخل پاسخ دسته ای استفاده شود، یکی برای هر پاسخ فرعی خطا.

  • عملیات ناهمزمان اگر یک فراخوانی API عملیات ناهمزمان را در پاسخ آن جاسازی کند، وضعیت آن عملیات باید مستقیماً با استفاده از پیام Status نمایش داده شود.

  • ورود به سیستم. اگر برخی از خطاهای API در گزارش‌ها ذخیره می‌شوند، پیام Status می‌تواند مستقیماً پس از هرگونه حذف مورد نیاز به دلایل امنیتی/حریم خصوصی استفاده شود.

نمایندگی JSON
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
زمینه های
code

number

کد وضعیت، که باید مقداری از google.rpc.Code باشد.

message

string

یک پیغام خطای برنامه‌نویس، که باید به زبان انگلیسی باشد. هر پیام خطای کاربر باید بومی سازی شده و در قسمت google.rpc.Status.details ارسال شود یا توسط مشتری بومی سازی شود.

details[]

object

لیستی از پیام هایی که حاوی جزئیات خطا هستند. مجموعه ای متداول از انواع پیام ها برای استفاده API ها وجود دارد.

یک شی حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .