Status

Loại Status xác định mô hình lỗi logic phù hợp với các môi trường lập trình khác nhau, bao gồm API REST và API RPC. Nó được sử dụng bởi gRPC . Mô hình lỗi được thiết kế như sau:

  • Đơn giản để sử dụng và hiểu cho hầu hết người dùng
  • Đủ linh hoạt để đáp ứng nhu cầu bất ngờ

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à chi tiết 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 bổ sung nếu cần. Thông báo lỗi phải là thông báo bằng tiếng Anh dành cho nhà phát triển để giúp nhà phát triển hiểu và giải quyết lỗi. Nếu cần một thông báo lỗi được bản địa hóa dành cho người dùng, hãy đặt thông báo đã bản địa hóa đó vào chi tiết lỗi hoặc bản địa hóa nó trong ứng dụng khách. Chi tiết lỗi tùy chọn có thể chứa thông tin tùy ý 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ể được sử dụng cho các tình trạng lỗi phổ biến.

Ánh xạ ngôn ngữ

Thông báo Status là sự trình bày logic của mô hình lỗi, nhưng nó không nhất thiết phải là định dạng dây thực tế. Khi thông báo Status được hiển thị trong các thư viện máy khách khác nhau và các giao thức dây khác nhau, nó có thể được ánh xạ khác nhau. Ví dụ: nó có thể sẽ được ánh xạ tới một số ngoại lệ trong Java, nhưng nhiều khả năng nó sẽ được ánh xạ tới một số mã lỗi trong C.

Công dụng khác

Mô hình lỗi và thông báo Status có thể được sử dụng trong nhiều môi trường khác nhau, 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 các môi trường khác nhau.

Ví dụ sử dụng mô hình lỗi này bao gồm:

  • Lỗi một phần. Nếu một dịch vụ cần trả lại lỗi một phần cho máy khách, dịch vụ đó có thể nhúng Status vào phản hồi thông thường để chỉ ra lỗi một phần.

  • Lỗi quy trình làm việc. Một quy trình công việc điển hình có nhiều bước. Mỗi bước có thể có thông báo Status để báo cáo lỗi.

  • Hoạt động hàng loạt. Nếu khách hà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 phải được sử dụng trực tiếp bên trong phản hồi hàng loạt, một thông báo cho mỗi phản hồi phụ lỗi.

  • Hoạt động không đồng bộ. Nếu lệnh gọi API nhúng hoạt động không đồng bộ dẫn đến phản hồi của nó thì trạng thái của các hoạt động đó sẽ được thể hiện 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ông báo Status có thể được sử dụng trực tiếp sau bất kỳ thao tác xóa nào cần thiết vì lý do bảo mật/quyền riêng tư.

Biểu diễn JSON
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Lĩnh vực
code

number

Mã trạng thái phải là giá trị enum của google.rpc.Code .

message

string

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 mà người dùng gặp phải phải được bản địa hóa và gửi trong trường google.rpc.Status.details hoặc được khách hàng bản địa hóa.

details[]

object

Danh sách các thông báo chứa chi tiết lỗi. Có một nhóm loại thông báo chung để API sử dụng.

Một đối tượng chứa các trường thuộc loại tùy ý. Trường bổ sung "@type" chứa URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" } .