Status

Loại Status xác định 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. Hàm này được gRPC sử dụng. Mô hình lỗi được thiết kế để:

  • Hầu hết người dùng đều dễ dàng sử dụng và dễ hiểu
  • Đủ linh hoạt để đáp ứng nhu cầu ngoài dự kiến

Tổng quan

Thông báo Status chứa 3 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à 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à khắc phục lỗi. Nếu cần thông báo lỗi dành cho người dùng đã được bản địa hoá, hãy đưa thông báo đã bản địa hoá vào chi tiết lỗi hoặc bản địa hoá thông báo đó trong ứng dụng. Thông tin chi tiết không bắt buộc về lỗi có thể chứa thông tin tuỳ ý về lỗi. Có một tập hợp các loại thông tin chi tiết về lỗi được xác định trước trong gói google.rpc mà bạn có thể dùng cho các điều kiện lỗi phổ biến.

Ánh xạ ngôn ngữ

Thông báo Status là cách trình bày 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 hiển thị trong nhiều thư viện ứng dụng và giao thức dây khác nhau, thì thông báo đó có thể được liên kết theo cách khác nhau. Ví dụ: dữ liệu này có thể được liên kết với một số ngoại lệ trong Java, nhưng có nhiều khả năng được liên kết với một số mã lỗi trong C.

Cách 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, nhằm 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 bao gồm:

  • Lỗi một phần. Nếu cần trả về 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ỉ báo lỗi một phần.

  • Lỗi quy trình làm việc. Một quy trình làm việc điển hình 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ì bạn nên sử dụng trực tiếp thông báo Status bên trong phản hồi hàng loạt, một thông báo cho từng phản hồi phụ lỗi.

  • Thao tác 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, thì trạng thái của các thao tác đó 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ì bạn có thể sử dụng trực tiếp thông báo Status sau khi thực hiện mọi thao tác xoá cần thiết vì lý do bảo mật/quyền riêng tư.

Biểu diễn dưới dạng JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Trường
code

number

Mã trạng thái, phải là một 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 dành cho người dùng đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc để ứng dụng bản địa hoá.

details[]

object

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

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