Package google.rpc

فهرست

درخواست بد

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

فیلدها
field_violations[]

FieldViolation

تمام تخلفات را در درخواست مشتری شرح می‌دهد.

نقض میدانی

نوعی پیام که برای توصیف یک فیلد درخواست خراب استفاده می‌شود.

فیلدها
field

string

مسیری که به یک فیلد در بدنه درخواست منتهی می‌شود. مقدار، دنباله‌ای از شناسه‌های جدا شده با نقطه خواهد بود که یک فیلد بافر پروتکل را مشخص می‌کنند.

موارد زیر را در نظر بگیرید:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

در این مثال، field in proto می‌تواند یکی از مقادیر زیر را بپذیرد:

  • full_name برای نقض در مقدار full_name
  • email_addresses[1].email برای تخلف در فیلد email اولین پیام email_addresses
  • email_addresses[3].type[2] ‎ برای نقض مقدار type دوم در پیام سوم email_addresses .

در JSON، مقادیر مشابه به صورت زیر نمایش داده می‌شوند:

  • fullName برای نقض در مقدار fullName
  • emailAddresses[1].email برای تخلف در فیلد email اولین پیام emailAddresses
  • emailAddresses[3].type[2] ‎ برای نقض مقدار type دوم در پیام سوم emailAddresses .
description

string

توضیحی در مورد اینکه چرا عنصر درخواست بد است.

reason

string

دلیل خطای سطح فیلد. این یک مقدار ثابت است که علت تقریبی خطای سطح فیلد را مشخص می‌کند. باید به طور منحصر به فرد نوع FieldViolation را در محدوده google.rpc.ErrorInfo.domain مشخص کند. این مقدار باید حداکثر ۶۳ کاراکتر باشد و با یک عبارت منظم [AZ][A-Z0-9_]+[A-Z0-9] مطابقت داشته باشد که نشان دهنده UPPER_SNAKE_CASE است.

localized_message

LocalizedMessage

یک پیام خطای محلی برای خطاهای سطح فیلد ارائه می‌دهد که بازگشت آن به مصرف‌کننده API ایمن است.

کد

کدهای خطای متعارف برای API های gRPC.

گاهی اوقات ممکن است چندین کد خطا اعمال شود. سرویس‌ها باید خاص‌ترین کد خطایی که اعمال می‌شود را برگردانند. برای مثال، اگر هر دو کد اعمال می‌شوند، OUT_OF_RANGE به FAILED_PRECONDITION ترجیح دهید. به طور مشابه NOT_FOUND یا ALREADY_EXISTS را به FAILED_PRECONDITION ترجیح دهید.

انوم‌ها
OK

خطا نیست؛ در صورت موفقیت برگردانده می‌شود.

نگاشت HTTP: 200 OK

CANCELLED

عملیات، معمولاً توسط تماس‌گیرنده، لغو می‌شد.

نگاشت HTTP: درخواست بسته شده کلاینت ۴۹۹

UNKNOWN

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

نگاشت HTTP: خطای ۵۰۰ سرور داخلی

INVALID_ARGUMENT

کلاینت یک آرگومان نامعتبر مشخص کرده است. توجه داشته باشید که این با FAILED_PRECONDITION متفاوت است. INVALID_ARGUMENT نشان دهنده آرگومان‌هایی است که صرف نظر از وضعیت سیستم، مشکل‌ساز هستند (مثلاً نام فایل ناقص).

نگاشت HTTP: درخواست نامناسب ۴۰۰

DEADLINE_EXCEEDED

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

نگاشت HTTP: زمان انتظار دروازه ۵۰۴

NOT_FOUND

برخی از موجودیت‌های درخواستی (مثلاً فایل یا دایرکتوری) یافت نشد.

نکته برای توسعه‌دهندگان سرور: اگر درخواستی برای کل یک کلاس از کاربران رد شود، مانند انتشار تدریجی ویژگی یا لیست دسترسی‌های بدون سند، می‌توان از NOT_FOUND استفاده کرد. اگر درخواستی برای برخی از کاربران در یک کلاس از کاربران رد شود، مانند کنترل دسترسی مبتنی بر کاربر، باید PERMISSION_DENIED استفاده شود.

نگاشت HTTP: خطای ۴۰۴ یافت نشد

ALREADY_EXISTS

موجودیتی که کلاینت سعی در ایجاد آن داشته است (مثلاً فایل یا دایرکتوری) از قبل وجود دارد.

نگاشت HTTP: تداخل ۴۰۹

PERMISSION_DENIED

فراخواننده مجوز اجرای عملیات مشخص شده را ندارد. PERMISSION_DENIED نباید برای رد شدن‌های ناشی از اتمام منابع استفاده شود (به جای آن برای این خطاها RESOURCE_EXHAUSTED استفاده کنید). PERMISSION_DENIED نباید در صورتی که فراخواننده قابل شناسایی نباشد استفاده شود (به جای آن برای این خطاها UNAUTHENTICATED استفاده کنید). این کد خطا به این معنی نیست که درخواست معتبر است یا موجودیت درخواست شده وجود دارد یا سایر پیش‌شرط‌ها را برآورده می‌کند.

نگاشت HTTP: ۴۰۳ ممنوع

UNAUTHENTICATED

درخواست، اعتبارنامه‌های احراز هویت معتبری برای عملیات ندارد.

نگاشت HTTP: خطای ۴۰۱ غیرمجاز

RESOURCE_EXHAUSTED

برخی از منابع به اتمام رسیده‌اند، شاید سهمیه هر کاربر، یا شاید کل سیستم فایل فضای کافی ندارد.

نگاشت HTTP: درخواست‌های بسیار زیاد ۴۲۹

FAILED_PRECONDITION

این عملیات رد شد زیرا سیستم در حالت مورد نیاز برای اجرای عملیات نیست. برای مثال، دایرکتوری که قرار است حذف شود خالی نیست، عملیات rmdir روی یک دایرکتوری غیر از دایرکتوری اعمال می‌شود و غیره.

پیاده‌سازی‌کنندگان سرویس می‌توانند از دستورالعمل‌های زیر برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE استفاده کنند: (الف) اگر کلاینت می‌تواند فقط فراخوانی ناموفق را دوباره امتحان کند، UNAVAILABLE استفاده کنید. (ب) اگر کلاینت باید در سطح بالاتری دوباره امتحان کند، ABORTED استفاده کنید. به عنوان مثال، هنگامی که یک تست و مجموعه مشخص شده توسط کلاینت با شکست مواجه می‌شود، نشان می‌دهد که کلاینت باید یک توالی خواندن-تغییر-نوشتن را مجدداً راه‌اندازی کند. (ج) اگر کلاینت نباید تا زمانی که وضعیت سیستم به طور صریح اصلاح نشده است، دوباره امتحان کند، FAILED_PRECONDITION استفاده کنید. به عنوان مثال، اگر "rmdir" به دلیل خالی نبودن دایرکتوری با شکست مواجه شود، FAILED_PRECONDITION باید برگردانده شود زیرا کلاینت نباید دوباره امتحان کند مگر اینکه فایل‌ها از دایرکتوری حذف شوند.

نگاشت HTTP: درخواست نامناسب ۴۰۰

ABORTED

این عملیات معمولاً به دلیل یک مشکل همزمانی مانند خرابی بررسی ترتیب‌سنج یا لغو تراکنش، لغو شد.

برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE به دستورالعمل‌های بالا مراجعه کنید.

نگاشت HTTP: تداخل ۴۰۹

OUT_OF_RANGE

این عملیات فراتر از محدوده‌ی معتبر انجام شده است. مثلاً جستجو یا خواندن فراتر از انتهای فایل.

برخلاف INVALID_ARGUMENT ، این خطا نشان‌دهنده مشکلی است که در صورت تغییر وضعیت سیستم ممکن است برطرف شود. برای مثال، یک سیستم فایل ۳۲ بیتی اگر از آن خواسته شود که در یک آفست که در محدوده [0,2^32-1] نیست، بخواند INVALID_ARGUMENT تولید می‌کند، اما اگر از آن خواسته شود از یک آفست که بزرگتر از اندازه فعلی فایل است، بخواند OUT_OF_RANGE تولید می‌کند.

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

نگاشت HTTP: درخواست نامناسب ۴۰۰

UNIMPLEMENTED

این عملیات در این سرویس پیاده‌سازی نشده یا پشتیبانی/فعال نشده است.

نگاشت HTTP: خطای ۵۰۱ پیاده‌سازی نشده است

INTERNAL

خطاهای داخلی. این بدان معناست که برخی از ثابت‌های مورد انتظار سیستم اصلی، دچار مشکل شده‌اند. این کد خطا برای خطاهای جدی در نظر گرفته شده است.

نگاشت HTTP: خطای ۵۰۰ سرور داخلی

UNAVAILABLE

سرویس در حال حاضر در دسترس نیست. این به احتمال زیاد یک وضعیت گذرا است که می‌توان با تلاش مجدد با یک backoff آن را اصلاح کرد. توجه داشته باشید که تلاش مجدد برای عملیات غیر خودتوان همیشه ایمن نیست.

برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE به دستورالعمل‌های بالا مراجعه کنید.

نگاشت HTTP: سرویس ۵۰۳ در دسترس نیست

DATA_LOSS

از دست رفتن یا خرابی غیرقابل بازیابی داده‌ها.

نگاشت HTTP: خطای ۵۰۰ سرور داخلی

اطلاعات خطا

علت خطا را با جزئیات ساختاریافته شرح می‌دهد.

نمونه‌ای از خطا هنگام تماس با API "pubsub.googleapis.com" در صورت فعال نبودن:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

این پاسخ نشان می‌دهد که API مربوط به pubsub.googleapis.com فعال نیست.

نمونه خطایی که هنگام تلاش برای ایجاد یک نمونه Spanner در منطقه‌ای که موجودی آن تمام شده است، بازگردانده می‌شود:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
فیلدها
reason

string

دلیل خطا. این یک مقدار ثابت است که علت تقریبی خطا را مشخص می‌کند. دلایل خطا در یک دامنه خاص از خطاها منحصر به فرد هستند. این باید حداکثر ۶۳ کاراکتر باشد و با یک عبارت منظم [AZ][A-Z0-9_]+[A-Z0-9] مطابقت داشته باشد که نشان دهنده UPPER_SNAKE_CASE است.

domain

string

گروه‌بندی منطقی که "دلیل" به آن تعلق دارد. دامنه خطا معمولاً نام سرویس ثبت‌شده ابزار یا محصولی است که خطا را ایجاد می‌کند. مثال: "pubsub.googleapis.com". اگر خطا توسط یک زیرساخت مشترک ایجاد شده باشد، دامنه خطا باید یک مقدار منحصر به فرد جهانی باشد که زیرساخت را مشخص می‌کند. برای زیرساخت API گوگل، دامنه خطا "googleapis.com" است.

metadata

map<string, string>

جزئیات ساختاریافته‌ی بیشتر در مورد این خطا.

کلیدها باید با یک عبارت منظم [az][a-zA-Z0-9-_]+ مطابقت داشته باشند، اما در حالت ایده‌آل باید lowerCamelCase باشند. همچنین، طول آنها باید به ۶۴ کاراکتر محدود شود. هنگام شناسایی مقدار فعلی یک محدودیت بیش از حد، واحدها باید در کلید باشند، نه در مقدار. برای مثال، به جای {"instanceLimit": "100/request"} ، باید به صورت {"instanceLimitPerRequest": "100"} برگردانده شود، اگر کلاینت از تعداد نمونه‌هایی که می‌تواند در یک درخواست (دسته‌ای) ایجاد شود، فراتر رود.

کمک

پیوندهایی به مستندات یا برای انجام یک اقدام خارج از محدوده ارائه می‌دهد.

برای مثال، اگر بررسی سهمیه با خطایی مبنی بر فعال نشدن سرویس مورد دسترسی توسط پروژه فراخوانی شده، ناموفق باشد، این خطا می‌تواند شامل یک URL باشد که مستقیماً به مکان مناسب در کنسول توسعه‌دهنده برای تغییر بخش اشاره می‌کند.

فیلدها

پیام محلی‌شده

یک پیام خطای محلی ارائه می‌دهد که بازگشت آن به کاربر ایمن است و می‌تواند به یک خطای RPC پیوست شود.

فیلدها
locale

string

زبان محلی مورد استفاده طبق مشخصات تعریف شده در https://www.rfc-editor.org/rfc/bcp/bcp47.txt . مثال‌ها عبارتند از: "en-US"، "fr-CH"، "es-MX"

message

string

پیام خطای محلی‌شده در زبان بالا.

درخواست اطلاعات

شامل فراداده‌هایی درباره درخواستی است که کاربران می‌توانند هنگام ثبت یک اشکال یا ارائه سایر اشکال بازخورد، آن را پیوست کنند.

فیلدها
request_id

string

یک رشته‌ی مبهم که فقط باید توسط سرویسی که آن را تولید می‌کند تفسیر شود. برای مثال، می‌توان از آن برای شناسایی درخواست‌ها در گزارش‌های سرویس استفاده کرد.

serving_data

string

هر داده‌ای که برای ارائه این درخواست استفاده شده است. به عنوان مثال، یک ردیابی پشته رمزگذاری شده که می‌تواند برای اشکال‌زدایی به ارائه دهنده خدمات ارسال شود.

وضعیت

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

می‌توانید اطلاعات بیشتری در مورد این مدل خطا و نحوه کار با آن را در راهنمای طراحی API بیابید.

فیلدها
code

int32

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

message

string

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

details[]

Any

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