Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2017 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""A client for the google.longrunning.operations meta-API.
17This is a client that deals with long-running operations that follow the
18pattern outlined by the `Google API Style Guide`_.
20When an API method normally takes long time to complete, it can be designed to
21return ``Operation`` to the client, and the client can use this interface to
22receive the real response asynchronously by polling the operation resource to
23receive the response.
25It is not a separate service, but rather an interface implemented by a larger
26service. The protocol-level definition is available at
27`google/longrunning/operations.proto`_. Typically, this will be constructed
28automatically by another client class to deal with operations.
30.. _Google API Style Guide:
31 https://cloud.google.com/apis/design/design_pattern
32 s#long_running_operations
33.. _google/longrunning/operations.proto:
34 https://github.com/googleapis/googleapis/blob/master/google/longrunning
35 /operations.proto
36"""
38import functools
40from google.api_core import exceptions as core_exceptions
41from google.api_core import gapic_v1
42from google.api_core import page_iterator
43from google.api_core import retry as retries
44from google.api_core import timeout as timeouts
45from google.longrunning import operations_pb2
46from grpc import Compression
49class OperationsClient(object):
50 """Client for interacting with long-running operations within a service.
52 Args:
53 channel (grpc.Channel): The gRPC channel associated with the service
54 that implements the ``google.longrunning.operations`` interface.
55 client_config (dict):
56 A dictionary of call options for each method. If not specified
57 the default configuration is used.
58 """
60 def __init__(self, channel, client_config=None):
61 # Create the gRPC client stub.
62 self.operations_stub = operations_pb2.OperationsStub(channel)
64 default_retry = retries.Retry(
65 initial=0.1, # seconds
66 maximum=60.0, # seconds
67 multiplier=1.3,
68 predicate=retries.if_exception_type(
69 core_exceptions.DeadlineExceeded,
70 core_exceptions.ServiceUnavailable,
71 ),
72 timeout=600.0, # seconds
73 )
74 default_timeout = timeouts.TimeToDeadlineTimeout(timeout=600.0)
76 default_compression = Compression.NoCompression
78 self._get_operation = gapic_v1.method.wrap_method(
79 self.operations_stub.GetOperation,
80 default_retry=default_retry,
81 default_timeout=default_timeout,
82 default_compression=default_compression,
83 )
85 self._list_operations = gapic_v1.method.wrap_method(
86 self.operations_stub.ListOperations,
87 default_retry=default_retry,
88 default_timeout=default_timeout,
89 default_compression=default_compression,
90 )
92 self._cancel_operation = gapic_v1.method.wrap_method(
93 self.operations_stub.CancelOperation,
94 default_retry=default_retry,
95 default_timeout=default_timeout,
96 default_compression=default_compression,
97 )
99 self._delete_operation = gapic_v1.method.wrap_method(
100 self.operations_stub.DeleteOperation,
101 default_retry=default_retry,
102 default_timeout=default_timeout,
103 default_compression=default_compression,
104 )
106 # Service calls
107 def get_operation(
108 self,
109 name,
110 retry=gapic_v1.method.DEFAULT,
111 timeout=gapic_v1.method.DEFAULT,
112 compression=gapic_v1.method.DEFAULT,
113 metadata=None,
114 ):
115 """Gets the latest state of a long-running operation.
117 Clients can use this method to poll the operation result at intervals
118 as recommended by the API service.
120 Example:
121 >>> from google.api_core import operations_v1
122 >>> api = operations_v1.OperationsClient()
123 >>> name = ''
124 >>> response = api.get_operation(name)
126 Args:
127 name (str): The name of the operation resource.
128 retry (google.api_core.retry.Retry): The retry strategy to use
129 when invoking the RPC. If unspecified, the default retry from
130 the client configuration will be used. If ``None``, then this
131 method will not retry the RPC at all.
132 timeout (float): The amount of time in seconds to wait for the RPC
133 to complete. Note that if ``retry`` is used, this timeout
134 applies to each individual attempt and the overall time it
135 takes for this method to complete may be longer. If
136 unspecified, the the default timeout in the client
137 configuration is used. If ``None``, then the RPC method will
138 not time out.
139 compression (grpc.Compression): An element of grpc.compression
140 e.g. grpc.compression.Gzip.
141 metadata (Optional[List[Tuple[str, str]]]):
142 Additional gRPC metadata.
144 Returns:
145 google.longrunning.operations_pb2.Operation: The state of the
146 operation.
148 Raises:
149 google.api_core.exceptions.GoogleAPICallError: If an error occurred
150 while invoking the RPC, the appropriate ``GoogleAPICallError``
151 subclass will be raised.
152 """
153 request = operations_pb2.GetOperationRequest(name=name)
155 # Add routing header
156 metadata = metadata or []
157 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
159 return self._get_operation(
160 request,
161 retry=retry,
162 timeout=timeout,
163 compression=compression,
164 metadata=metadata,
165 )
167 def list_operations(
168 self,
169 name,
170 filter_,
171 retry=gapic_v1.method.DEFAULT,
172 timeout=gapic_v1.method.DEFAULT,
173 compression=gapic_v1.method.DEFAULT,
174 metadata=None,
175 ):
176 """
177 Lists operations that match the specified filter in the request.
179 Example:
180 >>> from google.api_core import operations_v1
181 >>> api = operations_v1.OperationsClient()
182 >>> name = ''
183 >>>
184 >>> # Iterate over all results
185 >>> for operation in api.list_operations(name):
186 >>> # process operation
187 >>> pass
188 >>>
189 >>> # Or iterate over results one page at a time
190 >>> iter = api.list_operations(name)
191 >>> for page in iter.pages:
192 >>> for operation in page:
193 >>> # process operation
194 >>> pass
196 Args:
197 name (str): The name of the operation collection.
198 filter_ (str): The standard list filter.
199 retry (google.api_core.retry.Retry): The retry strategy to use
200 when invoking the RPC. If unspecified, the default retry from
201 the client configuration will be used. If ``None``, then this
202 method will not retry the RPC at all.
203 timeout (float): The amount of time in seconds to wait for the RPC
204 to complete. Note that if ``retry`` is used, this timeout
205 applies to each individual attempt and the overall time it
206 takes for this method to complete may be longer. If
207 unspecified, the the default timeout in the client
208 configuration is used. If ``None``, then the RPC method will
209 not time out.
210 compression (grpc.Compression): An element of grpc.compression
211 e.g. grpc.compression.Gzip.
212 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
213 metadata.
215 Returns:
216 google.api_core.page_iterator.Iterator: An iterator that yields
217 :class:`google.longrunning.operations_pb2.Operation` instances.
219 Raises:
220 google.api_core.exceptions.MethodNotImplemented: If the server
221 does not support this method. Services are not required to
222 implement this method.
223 google.api_core.exceptions.GoogleAPICallError: If an error occurred
224 while invoking the RPC, the appropriate ``GoogleAPICallError``
225 subclass will be raised.
226 """
227 # Create the request object.
228 request = operations_pb2.ListOperationsRequest(name=name, filter=filter_)
230 # Add routing header
231 metadata = metadata or []
232 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
234 # Create the method used to fetch pages
235 method = functools.partial(
236 self._list_operations,
237 retry=retry,
238 timeout=timeout,
239 compression=compression,
240 metadata=metadata,
241 )
243 iterator = page_iterator.GRPCIterator(
244 client=None,
245 method=method,
246 request=request,
247 items_field="operations",
248 request_token_field="page_token",
249 response_token_field="next_page_token",
250 )
252 return iterator
254 def cancel_operation(
255 self,
256 name,
257 retry=gapic_v1.method.DEFAULT,
258 timeout=gapic_v1.method.DEFAULT,
259 compression=gapic_v1.method.DEFAULT,
260 metadata=None,
261 ):
262 """Starts asynchronous cancellation on a long-running operation.
264 The server makes a best effort to cancel the operation, but success is
265 not guaranteed. Clients can use :meth:`get_operation` or service-
266 specific methods to check whether the cancellation succeeded or whether
267 the operation completed despite cancellation. On successful
268 cancellation, the operation is not deleted; instead, it becomes an
269 operation with an ``Operation.error`` value with a
270 ``google.rpc.Status.code`` of ``1``, corresponding to
271 ``Code.CANCELLED``.
273 Example:
274 >>> from google.api_core import operations_v1
275 >>> api = operations_v1.OperationsClient()
276 >>> name = ''
277 >>> api.cancel_operation(name)
279 Args:
280 name (str): The name of the operation resource to be cancelled.
281 retry (google.api_core.retry.Retry): The retry strategy to use
282 when invoking the RPC. If unspecified, the default retry from
283 the client configuration will be used. If ``None``, then this
284 method will not retry the RPC at all.
285 timeout (float): The amount of time in seconds to wait for the RPC
286 to complete. Note that if ``retry`` is used, this timeout
287 applies to each individual attempt and the overall time it
288 takes for this method to complete may be longer. If
289 unspecified, the the default timeout in the client
290 configuration is used. If ``None``, then the RPC method will
291 not time out.
292 compression (grpc.Compression): An element of grpc.compression
293 e.g. grpc.compression.Gzip.
294 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
295 metadata.
297 Raises:
298 google.api_core.exceptions.MethodNotImplemented: If the server
299 does not support this method. Services are not required to
300 implement this method.
301 google.api_core.exceptions.GoogleAPICallError: If an error occurred
302 while invoking the RPC, the appropriate ``GoogleAPICallError``
303 subclass will be raised.
304 """
305 # Create the request object.
306 request = operations_pb2.CancelOperationRequest(name=name)
308 # Add routing header
309 metadata = metadata or []
310 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
312 self._cancel_operation(
313 request,
314 retry=retry,
315 timeout=timeout,
316 compression=compression,
317 metadata=metadata,
318 )
320 def delete_operation(
321 self,
322 name,
323 retry=gapic_v1.method.DEFAULT,
324 timeout=gapic_v1.method.DEFAULT,
325 compression=gapic_v1.method.DEFAULT,
326 metadata=None,
327 ):
328 """Deletes a long-running operation.
330 This method indicates that the client is no longer interested in the
331 operation result. It does not cancel the operation.
333 Example:
334 >>> from google.api_core import operations_v1
335 >>> api = operations_v1.OperationsClient()
336 >>> name = ''
337 >>> api.delete_operation(name)
339 Args:
340 name (str): The name of the operation resource to be deleted.
341 retry (google.api_core.retry.Retry): The retry strategy to use
342 when invoking the RPC. If unspecified, the default retry from
343 the client configuration will be used. If ``None``, then this
344 method will not retry the RPC at all.
345 timeout (float): The amount of time in seconds to wait for the RPC
346 to complete. Note that if ``retry`` is used, this timeout
347 applies to each individual attempt and the overall time it
348 takes for this method to complete may be longer. If
349 unspecified, the the default timeout in the client
350 configuration is used. If ``None``, then the RPC method will
351 not time out.
352 compression (grpc.Compression): An element of grpc.compression
353 e.g. grpc.compression.Gzip.
354 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
355 metadata.
357 Raises:
358 google.api_core.exceptions.MethodNotImplemented: If the server
359 does not support this method. Services are not required to
360 implement this method.
361 google.api_core.exceptions.GoogleAPICallError: If an error occurred
362 while invoking the RPC, the appropriate ``GoogleAPICallError``
363 subclass will be raised.
364 """
365 # Create the request object.
366 request = operations_pb2.DeleteOperationRequest(name=name)
368 # Add routing header
369 metadata = metadata or []
370 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
372 self._delete_operation(
373 request,
374 retry=retry,
375 timeout=timeout,
376 compression=compression,
377 metadata=metadata,
378 )