Status

Status 類型會定義適用於不同程式設計環境 (包含 REST API 和遠端程序呼叫 (RPC) API) 的邏輯錯誤模型。gRPC 會使用這個模型。錯誤模型主要目的：

  • 讓大部分使用者容易使用和理解
  • 足夠靈活彈性，可以滿足意外需求

總覽

Status 訊息包含三部分資料：錯誤代碼、錯誤訊息和錯誤詳細資料。錯誤代碼應為 google.rpc.Code 的列舉值，但也可以視需要接受其他錯誤代碼。錯誤訊息應該是向開發人員顯示的英文訊息，可協助開發人員「瞭解」和「解決」錯誤。如果需要向本地使用者顯示的錯誤訊息，請在錯誤詳細資料中加入本地化訊息，或在用戶端中將錯誤訊息本地化。選用的錯誤詳細資料可能包含有關錯誤的任意資訊。套件 google.rpc 中有一組預先定義的錯誤詳細資料類型，可用於常見的錯誤狀況。

語言對應

Status 訊息是錯誤模型的邏輯表示法，但不一定是實際傳輸格式。在不同的用戶端程式庫和不同的傳輸通訊協定中公開 Status 訊息時，訊息會以不同的方式對應。例如，它可能會對應到 Java 中的某些例外狀況，但更有可能會對應到 C 中的某些錯誤代碼。

其他用法：

錯誤模型和 Status 訊息可用於各種環境 (無論是否有 API)，在不同的環境中提供一致的開發人員體驗。

這個錯誤模型的使用範例包括：

  • 部分錯誤。如果服務需要將部分錯誤傳回用戶端，可以在一般回應中嵌入 Status 來表示部分錯誤。

  • 工作流程錯誤。一般工作流程含有多個步驟。每個步驟可能都會顯示用於回報錯誤的 Status 訊息。

  • 批次作業。如果用戶端採用批次要求和批次回應，則應直接在批次回應中使用 Status 訊息，每個錯誤次回應各有一個。

  • 非同步作業。如果 API 呼叫在回應中嵌入非同步作業結果，則應使用 Status 訊息直接表示這些作業的狀態。

  • 記錄。如果部分 API 錯誤儲存在記錄檔中，則在基於安全性/隱私權理由執行任何必要的移除作業後，可以直接使用 Status 訊息。

JSON 表示法 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
欄位
code

number

狀態碼，應為 google.rpc.Code 的列舉值。

message

string

向開發人員顯示的錯誤訊息，應以英文呈現。凡是向使用者顯示的錯誤訊息，都應透過 google.rpc.Status.details 欄位進行本地化並傳送，或由用戶端進行本地化。

details[]

object

附有錯誤詳細資料的訊息清單。這是供 API 使用的一組常用訊息類型。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。