REST リソース: projects.locations.operations

リソース: Operation

このリソースは、ネットワーク API 呼び出しの結果の長時間実行オペレーションを示します。

JSON 表現 

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
フィールド
name

string

サーバーによって割り当てられる名前で、その名前を最初に返した同じサービス内でのみ一意になります。デフォルトの HTTP マッピングを使用している場合、name は operations/some/unique/name の形式になります。

metadata

object

オペレーションに関連付けられているサービス固有のメタデータ。通常は進捗情報や、作成日時などの共通メタデータが含まれます。一部のサービスでは、このようなメタデータが提供されないこともあります。メタデータがある場合、長時間実行オペレーションを返すメソッドでは、メタデータの型をドキュメント化しておく必要があります。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド "@type"。例: { "id": 1234, "@type": "types.example.com/standard/id" }。
done

boolean

値が false の場合は、オペレーションが進行中であることを意味します。true の場合、オペレーションは完了しており、error または response が利用可能です。

共用体フィールド result。オペレーションの結果。error または有効な response になります。done == false の場合は、error と response のいずれも設定されません。done == true の場合は、error または response のいずれか 1 つが設定されます。result に設定できるのは次のいずれかのみです。
error

object(Status)

失敗またはキャンセルされた場合のエラー結果。

response

object

成功した場合はオペレーションの通常のレスポンス。Delete のように、元のメソッドで成功時にデータが返されない場合、レスポンスは google.protobuf.Empty になります。元のメソッドが標準の Get/Create/Update である場合、レスポンスはリソースになります。他のメソッドについては、レスポンスのデータ型が XxxResponse（Xxx は元のメソッド名）になります。たとえば、元のメソッド名が TakeSnapshot() であれば、レスポンスのデータ型は TakeSnapshotResponse になると推測できます。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド "@type"。例: { "id": 1234, "@type": "types.example.com/standard/id" }。

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

number

ステータス コード google.rpc.Code の列挙値である必要があります。

message

string

デベロッパー向けのエラー メッセージ。英語で記述します。ユーザー向けのエラー メッセージはローカライズして google.rpc.Status.details フィールドで送信するか、クライアントでローカライズする必要があります。

details[]

object

エラーの詳細を保持するメッセージのリスト。API が使用する共通のメッセージ タイプのセットがあります。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド "@type"。例: { "id": 1234, "@type": "types.example.com/standard/id" }。

メソッド

cancel

 長時間実行オペレーションの非同期キャンセルを開始します。

delete

 長時間実行オペレーションを削除します。

get

 長時間実行オペレーションの最新状態を取得します。

list

 リクエストで指定されたフィルタに一致するオペレーションをリストします。