Package google.rpc
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Trạng thái
Loại Status xác định một mô hình lỗi logic phù hợp với nhiều môi trường lập trình, bao gồm cả API REST và API RPC. gRPC sử dụng khoá này. Mô hình lỗi được thiết kế để:
- Dễ sử dụng và dễ hiểu đối với hầu hết người dùng
- Đủ linh hoạt để đáp ứng những nhu cầu không mong muốn
Tổng quan
Thông báo Status chứa ba phần dữ liệu: mã lỗi, thông báo lỗi và thông tin chi tiết về lỗi. Mã lỗi phải là giá trị enum của google.rpc.Code, nhưng có thể chấp nhận các mã lỗi khác nếu cần. Thông báo lỗi phải là một thông báo bằng tiếng Anh dành cho nhà phát triển, giúp nhà phát triển understand và understand lỗi đó. Nếu cần thông báo lỗi được bản địa hoá cho người dùng, hãy đưa thông báo đã bản địa hoá đó vào phần thông tin chi tiết về lỗi hoặc bản địa hoá trong ứng dụng. Thông tin chi tiết về lỗi không bắt buộc có thể chứa thông tin tuỳ ý về lỗi. Có một tập hợp các loại chi tiết lỗi được xác định trước trong gói google.rpc có thể dùng cho các điều kiện lỗi phổ biến.
Lập bản đồ ngôn ngữ
Thông báo Status thể hiện logic của mô hình lỗi, nhưng không nhất thiết là định dạng dây thực tế. Khi thông báo Status xuất hiện ở nhiều thư viện ứng dụng và giao thức mạng, thông báo đó có thể được ánh xạ theo nhiều cách. Ví dụ: nó có thể sẽ được ánh xạ tới một số ngoại lệ trong Java, nhưng có nhiều khả năng sẽ được ánh xạ tới một số mã lỗi trong C.
Các trường hợp sử dụng khác
Mô hình lỗi và thông báo Status có thể được dùng trong nhiều môi trường (có hoặc không có API) để mang lại trải nghiệm nhất quán cho nhà phát triển trên nhiều môi trường.
Ví dụ về cách sử dụng mô hình lỗi này:
Lỗi một phần. Nếu cần trả về lỗi một phần cho ứng dụng khách, dịch vụ đó có thể nhúng Status vào phản hồi bình thường để chỉ ra lỗi một phần.
Lỗi quy trình công việc. Quy trình làm việc thông thường có nhiều bước. Mỗi bước có thể có một thông báo Status để báo cáo lỗi.
Thao tác theo lô. Nếu ứng dụng sử dụng yêu cầu hàng loạt và phản hồi hàng loạt, thì thông báo Status sẽ được dùng trực tiếp trong phản hồi hàng loạt, một thông báo cho mỗi phản hồi phụ khi gặp lỗi.
Thao tác không đồng bộ. Nếu một lệnh gọi API nhúng hoạt động không đồng bộ dẫn đến phản hồi, thì trạng thái của các hoạt động đó phải được biểu thị trực tiếp bằng thông báo Status.
Ghi nhật ký. Nếu một số lỗi API được lưu trữ trong nhật ký, thì bạn có thể sử dụng thông báo Status ngay sau khi loại bỏ nếu cần vì lý do bảo mật/quyền riêng tư.
| Các trường |
code |
int32
Mã trạng thái, phải là giá trị enum của google.rpc.Code.
|
message |
string
Một thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi dành cho người dùng phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc được ứng dụng bản địa hoá.
|
details[] |
Any
Danh sách các thông báo chứa thông tin chi tiết về lỗi. Có một tập hợp các loại thông báo phổ biến để API sử dụng.
|
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[[["\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. |"]]
