このリソースは、ネットワーク API 呼び出しの結果の長時間実行オペレーションを表します。
JSON 表現 | |
---|---|
{ "name": string, "metadata": { "@type": string, field1: ..., ... }, "done": boolean, // Union field |
フィールド | ||
---|---|---|
name |
サーバーによって割り当てられる名前で、最初にその名前を返す同じサーバー内でのみ一意になります。デフォルトの HTTP マッピングを使用している場合は、 |
|
metadata |
オペレーションに関連付けられているサービス固有のメタデータ。通常は進捗情報や、作成日時などの共通メタデータが含まれます。一部のサービスでは、このようなメタデータが提供されないこともあります。メタデータがある場合、長時間実行オペレーションを返すメソッドでは、メタデータの型をドキュメント化しておく必要があります。 任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド |
|
done |
この値が |
|
共用体フィールド result 。オペレーションの結果。error または有効な response になります。done == false の場合は、error と response のいずれも設定されません。done == true の場合は、error または response のいずれか 1 つが設定されます。result に設定できるのは次のいずれかのみです。 |
||
error |
失敗またはキャンセルされた場合のエラー結果。 |
|
response |
成功した場合はオペレーションの通常のレスポンス。元のメソッドで成功時にデータが返されない場合( 任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド |
Status
Status
型は、REST API や RPC API などのさまざまなプログラミング環境に適した論理エラーモデルを定義します。これは gRPC によって使用されます。エラーモデルは次のような目的で設計されています。
- 使い方が簡単で、ほとんどのユーザーが理解できる。
- 柔軟で予期しないニーズに対応できる。
概要
Status
メッセージには、エラーコード、エラー メッセージ、エラーの詳細という 3 種類のデータが含まれています。エラーコードは google.rpc.Code
の列挙値である必要がありますが、必要に応じて追加のエラーコードを受け入れることもできます。エラー メッセージは、デベロッパーによるエラーの理解と解決に役立つよう、デベロッパー向けの英語にする必要があります。ユーザー向けのローカライズされたエラー メッセージが必要な場合は、エラーの詳細にローカライズされたメッセージを入れるか、クライアントでローカライズします。オプションのエラーの詳細には、エラーに関する任意の情報を含めることができます。パッケージ google.rpc
には、一般的なエラー条件で使用できるエラーの詳細タイプが事前に定義されています。
言語マッピング
Status
メッセージはエラーモデルの論理表現ですが、必ずしも実際の送信形式ではありません。Status
メッセージがさまざまなクライアント ライブラリやさまざまな送信プロトコルで公開されると、異なったマッピングが行われる場合があります。たとえば、Java では一部の例外にマッピングされる可能性があり、C では一部のエラーコードにマッピングされる可能性が高くなります。
他の使用法
API を使用した、または使用しないさまざまな環境でエラーモデルと Status
メッセージを使用すると、さまざまな環境で一貫性のある使用感をデベロッパーに提供できます。
このエラーモデルの使用例には、次のようなものがあります。
部分的エラー。サービスでクライアントに部分的エラーを返す必要がある場合は、通常のレスポンスに
Status
を埋め込んで部分的エラーを表すことができます。ワークフロー エラー。通常のワークフローには複数のステップがあります。各ステップにはエラー報告の目的で、
Status
メッセージがある場合があります。バッチ オペレーション。クライアントでバッチ リクエストとバッチ レスポンスを使用する場合、
Status
メッセージは各エラーのサブレスポンスに 1 つずつ、バッチ レスポンスの中で直接使用する必要があります。非同期オペレーション。API 呼び出しでレスポンスに非同期オペレーションの結果を埋め込んでいる場合、このようなオペレーションのステータスは
Status
メッセージを使用して直接表す必要があります。ロギング。いくつかの API エラーがログに保存されている場合、メッセージ
Status
はセキュリティやプライバシー上の理由で必要とされる除去を行った後で、直接使用することができます。
JSON 表現 | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
フィールド | |
---|---|
code |
ステータス コード。 |
message |
デベロッパー向けのエラー メッセージ。英語で記述します。ユーザー向けのエラー メッセージは、ローカライズして |
details[] |
エラーの詳細を保持するメッセージのリスト。API が使用する共通のメッセージ タイプのセットがあります。 任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド |