Long-Running Operations¶
Futures for long-running operations returned from Google Cloud APIs.
These futures can be used to synchronously wait for the result of a
long-running operation using Operation.result()
:
operation = my_api_client.long_running_method()
result = operation.result()
Or asynchronously using callbacks and Operation.add_done_callback()
:
operation = my_api_client.long_running_method()
def my_callback(future):
result = future.result()
operation.add_done_callback(my_callback)
-
class
google.api_core.operation.
Operation
(operation, refresh, cancel, result_type, metadata_type=None, retry=<google.api_core.retry.Retry object>)[source]¶ Bases:
google.api_core.future.polling.PollingFuture
A Future for interacting with a Google API Long-Running Operation.
- Parameters
operation (google.longrunning.operations_pb2.Operation) – The initial operation.
refresh (Callable[[], Operation]) – A callable that returns the latest state of the operation.
cancel (Callable[[], None]) – A callable that tries to cancel the operation.
(func (metadata_type) – type): The protobuf type for the operation’s result.
(func – type): The protobuf type for the operation’s metadata.
retry (google.api_core.retry.Retry) – The retry configuration used when polling. This can be used to control how often
done()
is polled. Regardless of the retry’sdeadline
, it will be overridden by thetimeout
argument toresult()
.
-
cancel
()[source]¶ Attempt to cancel the operation.
- Returns
- True if the cancel RPC was made, False if the operation is
already complete.
- Return type
-
classmethod
deserialize
(payload)[source]¶ Deserialize a
google.longrunning.Operation
protocol buffer.- Parameters
payload (bytes) – A serialized operation protocol buffer.
- Returns
An Operation protobuf object.
- Return type
Operation
-
done
(retry=<google.api_core.retry.Retry object>)[source]¶ Checks to see if the operation is complete.
- Parameters
retry (google.api_core.retry.Retry) – (Optional) How to retry the RPC.
- Returns
True if the operation is complete, False otherwise.
- Return type
-
property
metadata
¶ the current operation metadata.
- Type
google.protobuf.Message
-
property
operation
¶ The current long-running operation.
- Type
google.longrunning.Operation
-
google.api_core.operation.
from_gapic
(operation, operations_client, result_type, **kwargs)[source]¶ Create an operation future from a gapic client.
This interacts with the long-running operations service (specific to a given API) via a gapic client.
- Parameters
operation (google.longrunning.operations_pb2.Operation) – The operation.
operations_client (google.api_core.operations_v1.OperationsClient) – The operations client.
result_type (
type()
) – The protobuf result type.kwargs – Keyword args passed into the
Operation
constructor.
- Returns
- The operation future to track the given
operation.
- Return type
Operation
-
google.api_core.operation.
from_grpc
(operation, operations_stub, result_type, **kwargs)[source]¶ Create an operation future using a gRPC client.
This interacts with the long-running operations service (specific to a given API) via gRPC.
- Parameters
operation (google.longrunning.operations_pb2.Operation) – The operation.
operations_stub (google.longrunning.operations_pb2.OperationsStub) – The operations stub.
result_type (
type()
) – The protobuf result type.kwargs – Keyword args passed into the
Operation
constructor.
- Returns
- The operation future to track the given
operation.
- Return type
Operation
-
google.api_core.operation.
from_http_json
(operation, api_request, result_type, **kwargs)[source]¶ Create an operation future using a HTTP/JSON client.
This interacts with the long-running operations service (specific to a given API) via HTTP/JSON.
- Parameters
- Returns
- The operation future to track the given
operation.
- Return type
Operation
Long-Running Operations in AsyncIO¶
AsyncIO futures for long-running operations returned from Google Cloud APIs.
These futures can be used to await for the result of a long-running operation
using AsyncOperation.result()
:
operation = my_api_client.long_running_method()
result = await operation.result()
Or asynchronously using callbacks and Operation.add_done_callback()
:
operation = my_api_client.long_running_method()
def my_callback(future):
result = await future.result()
operation.add_done_callback(my_callback)
-
class
google.api_core.operation_async.
AsyncOperation
(operation, refresh, cancel, result_type, metadata_type=None, retry=<google.api_core.retry_async.AsyncRetry object>)[source]¶ Bases:
google.api_core.future.async_future.AsyncFuture
A Future for interacting with a Google API Long-Running Operation.
- Parameters
operation (google.longrunning.operations_pb2.Operation) – The initial operation.
refresh (Callable[[], Operation]) – A callable that returns the latest state of the operation.
cancel (Callable[[], None]) – A callable that tries to cancel the operation.
(func (metadata_type) – type): The protobuf type for the operation’s result.
(func – type): The protobuf type for the operation’s metadata.
retry (google.api_core.retry.Retry) – The retry configuration used when polling. This can be used to control how often
done()
is polled. Regardless of the retry’sdeadline
, it will be overridden by thetimeout
argument toresult()
.
-
async
cancel
()[source]¶ Attempt to cancel the operation.
- Returns
- True if the cancel RPC was made, False if the operation is
already complete.
- Return type
-
classmethod
deserialize
(payload)[source]¶ Deserialize a
google.longrunning.Operation
protocol buffer.- Parameters
payload (bytes) – A serialized operation protocol buffer.
- Returns
An Operation protobuf object.
- Return type
Operation
-
async
done
(retry=<google.api_core.retry_async.AsyncRetry object>)[source]¶ Checks to see if the operation is complete.
- Parameters
retry (google.api_core.retry.Retry) – (Optional) How to retry the RPC.
- Returns
True if the operation is complete, False otherwise.
- Return type
-
property
metadata
¶ the current operation metadata.
- Type
google.protobuf.Message
-
property
operation
¶ The current long-running operation.
- Type
google.longrunning.Operation
-
google.api_core.operation_async.
from_gapic
(operation, operations_client, result_type, **kwargs)[source]¶ Create an operation future from a gapic client.
This interacts with the long-running operations service (specific to a given API) via a gapic client.
- Parameters
operation (google.longrunning.operations_pb2.Operation) – The operation.
operations_client (google.api_core.operations_v1.OperationsClient) – The operations client.
result_type (
type()
) – The protobuf result type.kwargs – Keyword args passed into the
Operation
constructor.
- Returns
- The operation future to track the given
operation.
- Return type
Operation