Status

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

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

總覽

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

語言對應

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

其他用法：

無論是否使用 API，錯誤模型和 Status 訊息都適用於各種環境，可為不同環境提供一致的開發人員體驗。

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

  • 部分錯誤。如果服務需要向用戶端傳回部分錯誤，可以在正常回應中嵌入 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" }。