1# Copyright 2020 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. 14 15"""An async client for the google.longrunning.operations meta-API. 16 17.. _Google API Style Guide: 18 https://cloud.google.com/apis/design/design_pattern 19 s#long_running_operations 20.. _google/longrunning/operations.proto: 21 https://github.com/googleapis/googleapis/blob/master/google/longrunning 22 /operations.proto 23""" 24 25import functools 26 27from google.api_core import gapic_v1, page_iterator_async 28from google.api_core.operations_v1 import operations_client_config 29from google.longrunning import operations_pb2 30 31 32class OperationsAsyncClient: 33 """Async client for interacting with long-running operations. 34 35 Args: 36 channel (aio.Channel): The gRPC AsyncIO channel associated with the 37 service that implements the ``google.longrunning.operations`` 38 interface. 39 client_config (dict): 40 A dictionary of call options for each method. If not specified 41 the default configuration is used. 42 """ 43 44 def __init__(self, channel, client_config=operations_client_config.config): 45 # Create the gRPC client stub with gRPC AsyncIO channel. 46 self.operations_stub = operations_pb2.OperationsStub(channel) 47 48 # Create all wrapped methods using the interface configuration. 49 # The interface config contains all of the default settings for retry 50 # and timeout for each RPC method. 51 interfaces = client_config["interfaces"] 52 interface_config = interfaces["google.longrunning.Operations"] 53 method_configs = gapic_v1.config_async.parse_method_configs(interface_config) 54 55 self._get_operation = gapic_v1.method_async.wrap_method( 56 self.operations_stub.GetOperation, 57 default_retry=method_configs["GetOperation"].retry, 58 default_timeout=method_configs["GetOperation"].timeout, 59 ) 60 61 self._list_operations = gapic_v1.method_async.wrap_method( 62 self.operations_stub.ListOperations, 63 default_retry=method_configs["ListOperations"].retry, 64 default_timeout=method_configs["ListOperations"].timeout, 65 ) 66 67 self._cancel_operation = gapic_v1.method_async.wrap_method( 68 self.operations_stub.CancelOperation, 69 default_retry=method_configs["CancelOperation"].retry, 70 default_timeout=method_configs["CancelOperation"].timeout, 71 ) 72 73 self._delete_operation = gapic_v1.method_async.wrap_method( 74 self.operations_stub.DeleteOperation, 75 default_retry=method_configs["DeleteOperation"].retry, 76 default_timeout=method_configs["DeleteOperation"].timeout, 77 ) 78 79 async def get_operation( 80 self, 81 name, 82 retry=gapic_v1.method_async.DEFAULT, 83 timeout=gapic_v1.method_async.DEFAULT, 84 metadata=None, 85 ): 86 """Gets the latest state of a long-running operation. 87 88 Clients can use this method to poll the operation result at intervals 89 as recommended by the API service. 90 91 Example: 92 >>> from google.api_core import operations_v1 93 >>> api = operations_v1.OperationsClient() 94 >>> name = '' 95 >>> response = await api.get_operation(name) 96 97 Args: 98 name (str): The name of the operation resource. 99 retry (google.api_core.retry.Retry): The retry strategy to use 100 when invoking the RPC. If unspecified, the default retry from 101 the client configuration will be used. If ``None``, then this 102 method will not retry the RPC at all. 103 timeout (float): The amount of time in seconds to wait for the RPC 104 to complete. Note that if ``retry`` is used, this timeout 105 applies to each individual attempt and the overall time it 106 takes for this method to complete may be longer. If 107 unspecified, the the default timeout in the client 108 configuration is used. If ``None``, then the RPC method will 109 not time out. 110 metadata (Optional[List[Tuple[str, str]]]): 111 Additional gRPC metadata. 112 113 Returns: 114 google.longrunning.operations_pb2.Operation: The state of the 115 operation. 116 117 Raises: 118 google.api_core.exceptions.GoogleAPICallError: If an error occurred 119 while invoking the RPC, the appropriate ``GoogleAPICallError`` 120 subclass will be raised. 121 """ 122 request = operations_pb2.GetOperationRequest(name=name) 123 return await self._get_operation(request, retry=retry, timeout=timeout, metadata=metadata) 124 125 async def list_operations( 126 self, 127 name, 128 filter_, 129 retry=gapic_v1.method_async.DEFAULT, 130 timeout=gapic_v1.method_async.DEFAULT, 131 metadata=None, 132 ): 133 """ 134 Lists operations that match the specified filter in the request. 135 136 Example: 137 >>> from google.api_core import operations_v1 138 >>> api = operations_v1.OperationsClient() 139 >>> name = '' 140 >>> 141 >>> # Iterate over all results 142 >>> for operation in await api.list_operations(name): 143 >>> # process operation 144 >>> pass 145 >>> 146 >>> # Or iterate over results one page at a time 147 >>> iter = await api.list_operations(name) 148 >>> for page in iter.pages: 149 >>> for operation in page: 150 >>> # process operation 151 >>> pass 152 153 Args: 154 name (str): The name of the operation collection. 155 filter_ (str): The standard list filter. 156 retry (google.api_core.retry.Retry): The retry strategy to use 157 when invoking the RPC. If unspecified, the default retry from 158 the client configuration will be used. If ``None``, then this 159 method will not retry the RPC at all. 160 timeout (float): The amount of time in seconds to wait for the RPC 161 to complete. Note that if ``retry`` is used, this timeout 162 applies to each individual attempt and the overall time it 163 takes for this method to complete may be longer. If 164 unspecified, the the default timeout in the client 165 configuration is used. If ``None``, then the RPC method will 166 not time out. 167 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC 168 metadata. 169 170 Returns: 171 google.api_core.page_iterator.Iterator: An iterator that yields 172 :class:`google.longrunning.operations_pb2.Operation` instances. 173 174 Raises: 175 google.api_core.exceptions.MethodNotImplemented: If the server 176 does not support this method. Services are not required to 177 implement this method. 178 google.api_core.exceptions.GoogleAPICallError: If an error occurred 179 while invoking the RPC, the appropriate ``GoogleAPICallError`` 180 subclass will be raised. 181 """ 182 # Create the request object. 183 request = operations_pb2.ListOperationsRequest(name=name, filter=filter_) 184 185 # Create the method used to fetch pages 186 method = functools.partial(self._list_operations, retry=retry, timeout=timeout, metadata=metadata) 187 188 iterator = page_iterator_async.AsyncGRPCIterator( 189 client=None, 190 method=method, 191 request=request, 192 items_field="operations", 193 request_token_field="page_token", 194 response_token_field="next_page_token", 195 ) 196 197 return iterator 198 199 async def cancel_operation( 200 self, 201 name, 202 retry=gapic_v1.method_async.DEFAULT, 203 timeout=gapic_v1.method_async.DEFAULT, 204 metadata=None, 205 ): 206 """Starts asynchronous cancellation on a long-running operation. 207 208 The server makes a best effort to cancel the operation, but success is 209 not guaranteed. Clients can use :meth:`get_operation` or service- 210 specific methods to check whether the cancellation succeeded or whether 211 the operation completed despite cancellation. On successful 212 cancellation, the operation is not deleted; instead, it becomes an 213 operation with an ``Operation.error`` value with a 214 ``google.rpc.Status.code`` of ``1``, corresponding to 215 ``Code.CANCELLED``. 216 217 Example: 218 >>> from google.api_core import operations_v1 219 >>> api = operations_v1.OperationsClient() 220 >>> name = '' 221 >>> api.cancel_operation(name) 222 223 Args: 224 name (str): The name of the operation resource to be cancelled. 225 retry (google.api_core.retry.Retry): The retry strategy to use 226 when invoking the RPC. If unspecified, the default retry from 227 the client configuration will be used. If ``None``, then this 228 method will not retry the RPC at all. 229 timeout (float): The amount of time in seconds to wait for the RPC 230 to complete. Note that if ``retry`` is used, this timeout 231 applies to each individual attempt and the overall time it 232 takes for this method to complete may be longer. If 233 unspecified, the the default timeout in the client 234 configuration is used. If ``None``, then the RPC method will 235 not time out. 236 237 Raises: 238 google.api_core.exceptions.MethodNotImplemented: If the server 239 does not support this method. Services are not required to 240 implement this method. 241 google.api_core.exceptions.GoogleAPICallError: If an error occurred 242 while invoking the RPC, the appropriate ``GoogleAPICallError`` 243 subclass will be raised. 244 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC 245 metadata. 246 """ 247 # Create the request object. 248 request = operations_pb2.CancelOperationRequest(name=name) 249 await self._cancel_operation(request, retry=retry, timeout=timeout, metadata=metadata) 250 251 async def delete_operation( 252 self, 253 name, 254 retry=gapic_v1.method_async.DEFAULT, 255 timeout=gapic_v1.method_async.DEFAULT, 256 metadata=None, 257 ): 258 """Deletes a long-running operation. 259 260 This method indicates that the client is no longer interested in the 261 operation result. It does not cancel the operation. 262 263 Example: 264 >>> from google.api_core import operations_v1 265 >>> api = operations_v1.OperationsClient() 266 >>> name = '' 267 >>> api.delete_operation(name) 268 269 Args: 270 name (str): The name of the operation resource to be deleted. 271 retry (google.api_core.retry.Retry): The retry strategy to use 272 when invoking the RPC. If unspecified, the default retry from 273 the client configuration will be used. If ``None``, then this 274 method will not retry the RPC at all. 275 timeout (float): The amount of time in seconds to wait for the RPC 276 to complete. Note that if ``retry`` is used, this timeout 277 applies to each individual attempt and the overall time it 278 takes for this method to complete may be longer. If 279 unspecified, the the default timeout in the client 280 configuration is used. If ``None``, then the RPC method will 281 not time out. 282 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC 283 metadata. 284 285 Raises: 286 google.api_core.exceptions.MethodNotImplemented: If the server 287 does not support this method. Services are not required to 288 implement this method. 289 google.api_core.exceptions.GoogleAPICallError: If an error occurred 290 while invoking the RPC, the appropriate ``GoogleAPICallError`` 291 subclass will be raised. 292 """ 293 # Create the request object. 294 request = operations_pb2.DeleteOperationRequest(name=name) 295 await self._delete_operation(request, retry=retry, timeout=timeout, metadata=metadata) 296