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" } 。