パッケージ google.longrunning

インデックス

オペレーション

API サービスで長時間実行オペレーションを管理します。

完了するまでの時間が通常でも長くなる API メソッドについては、クライアントに Operation を返すように設計できます。クライアントはこのインターフェースを使用することで、オペレーション リソースをポーリングして実際のレスポンスを非同期的に受信したり、あるいはオペレーション リソースを別の API（Google Cloud Pub/Sub API など）に渡してレスポンスを受信したりできます。長時間継続する操作を返す API サービスでは、デベロッパーがクライアントの動作の一貫性を期待できるように、Operations インターフェースを実装する必要があります。

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty)

長時間実行オペレーションの非同期キャンセルを開始します。サーバーはオペレーションをキャンセルするために最善の努力を行いますが、成功は保証されません。このメソッドがサーバーでサポートされていない場合は、サーバーから google.rpc.Code.UNIMPLEMENTED が返されます。クライアントは Operations.GetOperation などのメソッドを使用して、キャンセルが成功したかどうか、あるいはキャンセルしたにもかかわらずオペレーションが完了したかどうかを確認できます。キャンセルが成功すると、そのオペレーションは削除されず、Operation.error 値を持つオペレーションになり、google.rpc.Status.code が 1 になります。これは、Code.CANCELLED に相当します。

承認スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

長時間実行オペレーションを削除します。このメソッドは、クライアントがそのオペレーション結果に関心がなくなったことを表しています。このメソッドではオペレーションはキャンセルされません。このメソッドがサーバーでサポートされていない場合は、サーバーから google.rpc.Code.UNIMPLEMENTED が返されます。

承認スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

長時間実行オペレーションの最新の状態を取得します。クライアントはこのメソッドを使用して、API サービスで推奨される間隔でオペレーションの結果をポーリングできます。

承認スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

リクエストで指定したフィルタに一致するオペレーションを一覧表示します。このメソッドがサーバーでサポートされていない場合は、UNIMPLEMENTED を返します。

注: name バインディングを使用すると、users/*/operations などの異なるリソース名スキームを使用するために、API サービスがバインディングをオーバーライドできます。バインディングをオーバーライドするときに、API サービスは "/v1/{name=users/*}/operations" のようなバインディングをサービス構成に追加する場合があります。下位互換性を維持するため、デフォルトの名前にはオペレーションのコレクション ID が含まれています。ただし、オーバーライドを行うユーザーは、名前のバインディングが親リソースであり、オペレーション コレクション ID がないことを確認する必要があります。

承認スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

指定された長時間実行オペレーションが完了するか、指定されたタイムアウトに達するまで待機し、最新の状態を返します。オペレーションがすでに完了している場合、すぐに最新の状態が返されます。指定されたタイムアウトがデフォルトの HTTP/RPC タイムアウトを上回る場合、HTTP/RPC タイムアウトが使用されます。サーバーがこのメソッドをサポートしていない場合は、google.rpc.Code.UNIMPLEMENTED を返します。このメソッドはベスト エフォート ベースです。指定されたタイムアウト（直前を含む）の前に最新の状態を返すことがあります。つまり、すぐにレスポンスがあったとしても、オペレーションが完了したことを保証するものではありません。

承認スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/cloud-platform

詳細については、認証の概要をご覧ください。

CancelOperationRequest

Operations.CancelOperation に対するリクエスト メッセージ。

フィールド
name

string

キャンセルするオペレーション リソースの名前。

DeleteOperationRequest

Operations.DeleteOperation に対するリクエスト メッセージ。

フィールド
name

string

削除するオペレーション リソースの名前。

GetOperationRequest

Operations.GetOperation に対するリクエスト メッセージ。

フィールド
name

string

オペレーション リソースの名前。

ListOperationsRequest

Operations.ListOperations に対するリクエスト メッセージ。

フィールド
name

string

オペレーションの親リソースの名前。

filter

string

リクエストの結果をフィルタリングする式。

  • operation_id - = または != を使用する場合。
  • done - = または != を使用する場合。
  • works_on - = または != を使用する場合。

フィルタの使用例:

  • done=true --> オペレーションの実行が終了しました。
  • worksOn = projects/my-project/locations/us-central1/datasets/5 --> オペレーションは、ID 5 のデータセットに対して機能します。
  • worksOn = projects/my-project/locations/us-central1/models/15 --> オペレーションは、ID 15 のモデルに対して機能します。
page_size

int32

標準的なリストのページサイズ。

page_token

string

標準的なリストのページトークン。

ListOperationsResponse

Operations.ListOperations に対するレスポンス メッセージ。

フィールド
operations[]

Operation

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

string

標準リスト ネクストページ トークン。

Operation

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

フィールド
name

string

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

metadata

Any

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

done

bool

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

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

Status

オペレーションが失敗またはキャンセルされた場合のエラー結果。

response

Any

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

WaitOperationRequest

Operations.WaitOperation に対するリクエスト メッセージ。

フィールド
name

string

待機するオペレーション リソースの名前。

timeout

Duration

タイムアウトするまでの最大待機時間。空白のままにした場合、待機時間は基になる HTTP/RPC プロトコルによって許可される最長の時間になります。RPC コンテキストの期限も指定されている場合は、短い方が使用されます。