Package google.rpc

索引

狀態

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

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

總覽

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

語言對應

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

其他用法：

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

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

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

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

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

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

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

欄位
code

int32

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

string

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

Any

包含錯誤詳細資料的訊息清單。API 可以使用一組常用的訊息類型。