Package google.rpc
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
وضعیت
نوع 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 می‌تواند مستقیماً پس از هرگونه حذف مورد نیاز به دلایل امنیتی/حریم خصوصی استفاده شود.
| زمینه های |
|---|
code | int32 کد وضعیت، که باید مقداری از google.rpc.Code باشد. |
message | string یک پیغام خطای برنامه‌نویس، که باید به زبان انگلیسی باشد. هر پیام خطای کاربر باید بومی سازی شده و در قسمت google.rpc.Status.details ارسال شود یا توسط مشتری بومی سازی شود. |
details[] | Any لیستی از پیام هایی که حاوی جزئیات خطا هستند. مجموعه ای متداول از انواع پیام ها برای استفاده API ها وجود دارد. |
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-24 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe \u003ccode\u003eStatus\u003c/code\u003e type defines a consistent and flexible error model suitable for various programming environments, including REST APIs and RPC APIs.\u003c/p\u003e\n"],["\u003cp\u003eIt provides three key pieces of information: an error code using \u003ccode\u003egoogle.rpc.Code\u003c/code\u003e, a developer-facing English error message, and optional error details for context.\u003c/p\u003e\n"],["\u003cp\u003eWhile logically represented by the \u003ccode\u003eStatus\u003c/code\u003e message, its actual implementation may vary across languages and wire protocols.\u003c/p\u003e\n"],["\u003cp\u003eThis error model can be utilized in diverse scenarios beyond APIs to ensure a uniform developer experience, including partial errors, workflow errors, batch operations, and asynchronous operations.\u003c/p\u003e\n"]]],["The `Status` message defines an error model with three data pieces: `code`, `message`, and `details`. The `code` is an error code, `message` is a developer-facing English error message, and `details` contains additional error information. This model can be used for partial, workflow, batch, and asynchronous operations and in logging. It is designed for simplicity and flexibility and is adaptable across different programming environments and API types, with a mapping system that can change based on implementation.\n"],null,["# Package google.rpc\n\nIndex\n-----\n\n- [Status](/assistant/sdk/reference/rpc/google.rpc#google.rpc.Status) (message)\n\nStatus\n------\n\nThe `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). The error model is designed to be:\n\n- Simple to use and understand for most users\n- Flexible enough to meet unexpected needs\n\n#### Overview\n\nThe `Status` message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of `google.rpc.Code`, but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers *understand* and *resolve* the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package `google.rpc` that can be used for common error conditions.\n\n#### Language mapping\n\nThe `Status` message is the logical representation of the error model, but it is not necessarily the actual wire format. When the `Status` message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C.\n\n#### Other uses\n\nThe error model and the `Status` message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments.\n\nExample uses of this error model include:\n\n- Partial errors. If a service needs to return partial errors to the client, it may embed the `Status` in the normal response to indicate the partial errors.\n\n- Workflow errors. A typical workflow has multiple steps. Each step may have a `Status` message for error reporting.\n\n- Batch operations. If a client uses batch request and batch response, the `Status` message should be used directly inside batch response, one for each error sub-response.\n\n- Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the `Status` message.\n\n- Logging. If some API errors are stored in logs, the message `Status` could be used directly after any stripping needed for security/privacy reasons.\n\n| Fields ||\n|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `code` | `int32` The status code, which should be an enum value of `google.rpc.Code`. |\n| `message` | `string` A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details](/assistant/sdk/reference/rpc/google.rpc#google.rpc.Status.FIELDS.repeated.google.protobuf.Any.google.rpc.Status.details) field, or localized by the client. |\n| `details[]` | [Any](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Any) A list of messages that carry the error details. There is a common set of message types for APIs to use. |"]]
