Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/resourcemanager_v3/services/folders/async_client.py: 34%
202 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-06 06:03 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2022 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from collections import OrderedDict
17import functools
18import re
19from typing import (
20 Dict,
21 Mapping,
22 MutableMapping,
23 MutableSequence,
24 Optional,
25 Sequence,
26 Tuple,
27 Type,
28 Union,
29)
31from google.api_core import exceptions as core_exceptions
32from google.api_core import gapic_v1
33from google.api_core import retry as retries
34from google.api_core.client_options import ClientOptions
35from google.auth import credentials as ga_credentials # type: ignore
36from google.oauth2 import service_account # type: ignore
38from google.cloud.resourcemanager_v3 import gapic_version as package_version
40try:
41 OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
42except AttributeError: # pragma: NO COVER
43 OptionalRetry = Union[retries.Retry, object] # type: ignore
45from google.api_core import operation # type: ignore
46from google.api_core import operation_async # type: ignore
47from google.iam.v1 import iam_policy_pb2 # type: ignore
48from google.iam.v1 import policy_pb2 # type: ignore
49from google.longrunning import operations_pb2
50from google.protobuf import field_mask_pb2 # type: ignore
51from google.protobuf import timestamp_pb2 # type: ignore
53from google.cloud.resourcemanager_v3.services.folders import pagers
54from google.cloud.resourcemanager_v3.types import folders
56from .client import FoldersClient
57from .transports.base import DEFAULT_CLIENT_INFO, FoldersTransport
58from .transports.grpc_asyncio import FoldersGrpcAsyncIOTransport
61class FoldersAsyncClient:
62 """Manages Cloud Platform folder resources.
63 Folders can be used to organize the resources under an
64 organization and to control the policies applied to groups of
65 resources.
66 """
68 _client: FoldersClient
70 DEFAULT_ENDPOINT = FoldersClient.DEFAULT_ENDPOINT
71 DEFAULT_MTLS_ENDPOINT = FoldersClient.DEFAULT_MTLS_ENDPOINT
73 folder_path = staticmethod(FoldersClient.folder_path)
74 parse_folder_path = staticmethod(FoldersClient.parse_folder_path)
75 common_billing_account_path = staticmethod(
76 FoldersClient.common_billing_account_path
77 )
78 parse_common_billing_account_path = staticmethod(
79 FoldersClient.parse_common_billing_account_path
80 )
81 common_folder_path = staticmethod(FoldersClient.common_folder_path)
82 parse_common_folder_path = staticmethod(FoldersClient.parse_common_folder_path)
83 common_organization_path = staticmethod(FoldersClient.common_organization_path)
84 parse_common_organization_path = staticmethod(
85 FoldersClient.parse_common_organization_path
86 )
87 common_project_path = staticmethod(FoldersClient.common_project_path)
88 parse_common_project_path = staticmethod(FoldersClient.parse_common_project_path)
89 common_location_path = staticmethod(FoldersClient.common_location_path)
90 parse_common_location_path = staticmethod(FoldersClient.parse_common_location_path)
92 @classmethod
93 def from_service_account_info(cls, info: dict, *args, **kwargs):
94 """Creates an instance of this client using the provided credentials
95 info.
97 Args:
98 info (dict): The service account private key info.
99 args: Additional arguments to pass to the constructor.
100 kwargs: Additional arguments to pass to the constructor.
102 Returns:
103 FoldersAsyncClient: The constructed client.
104 """
105 return FoldersClient.from_service_account_info.__func__(FoldersAsyncClient, info, *args, **kwargs) # type: ignore
107 @classmethod
108 def from_service_account_file(cls, filename: str, *args, **kwargs):
109 """Creates an instance of this client using the provided credentials
110 file.
112 Args:
113 filename (str): The path to the service account private key json
114 file.
115 args: Additional arguments to pass to the constructor.
116 kwargs: Additional arguments to pass to the constructor.
118 Returns:
119 FoldersAsyncClient: The constructed client.
120 """
121 return FoldersClient.from_service_account_file.__func__(FoldersAsyncClient, filename, *args, **kwargs) # type: ignore
123 from_service_account_json = from_service_account_file
125 @classmethod
126 def get_mtls_endpoint_and_cert_source(
127 cls, client_options: Optional[ClientOptions] = None
128 ):
129 """Return the API endpoint and client cert source for mutual TLS.
131 The client cert source is determined in the following order:
132 (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
133 client cert source is None.
134 (2) if `client_options.client_cert_source` is provided, use the provided one; if the
135 default client cert source exists, use the default one; otherwise the client cert
136 source is None.
138 The API endpoint is determined in the following order:
139 (1) if `client_options.api_endpoint` if provided, use the provided one.
140 (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
141 default mTLS endpoint; if the environment variable is "never", use the default API
142 endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
143 use the default API endpoint.
145 More details can be found at https://google.aip.dev/auth/4114.
147 Args:
148 client_options (google.api_core.client_options.ClientOptions): Custom options for the
149 client. Only the `api_endpoint` and `client_cert_source` properties may be used
150 in this method.
152 Returns:
153 Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
154 client cert source to use.
156 Raises:
157 google.auth.exceptions.MutualTLSChannelError: If any errors happen.
158 """
159 return FoldersClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
161 @property
162 def transport(self) -> FoldersTransport:
163 """Returns the transport used by the client instance.
165 Returns:
166 FoldersTransport: The transport used by the client instance.
167 """
168 return self._client.transport
170 get_transport_class = functools.partial(
171 type(FoldersClient).get_transport_class, type(FoldersClient)
172 )
174 def __init__(
175 self,
176 *,
177 credentials: Optional[ga_credentials.Credentials] = None,
178 transport: Union[str, FoldersTransport] = "grpc_asyncio",
179 client_options: Optional[ClientOptions] = None,
180 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
181 ) -> None:
182 """Instantiates the folders client.
184 Args:
185 credentials (Optional[google.auth.credentials.Credentials]): The
186 authorization credentials to attach to requests. These
187 credentials identify the application to the service; if none
188 are specified, the client will attempt to ascertain the
189 credentials from the environment.
190 transport (Union[str, ~.FoldersTransport]): The
191 transport to use. If set to None, a transport is chosen
192 automatically.
193 client_options (ClientOptions): Custom options for the client. It
194 won't take effect if a ``transport`` instance is provided.
195 (1) The ``api_endpoint`` property can be used to override the
196 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
197 environment variable can also be used to override the endpoint:
198 "always" (always use the default mTLS endpoint), "never" (always
199 use the default regular endpoint) and "auto" (auto switch to the
200 default mTLS endpoint if client certificate is present, this is
201 the default value). However, the ``api_endpoint`` property takes
202 precedence if provided.
203 (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
204 is "true", then the ``client_cert_source`` property can be used
205 to provide client certificate for mutual TLS transport. If
206 not provided, the default SSL client certificate will be used if
207 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
208 set, no client certificate will be used.
210 Raises:
211 google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
212 creation failed for any reason.
213 """
214 self._client = FoldersClient(
215 credentials=credentials,
216 transport=transport,
217 client_options=client_options,
218 client_info=client_info,
219 )
221 async def get_folder(
222 self,
223 request: Optional[Union[folders.GetFolderRequest, dict]] = None,
224 *,
225 name: Optional[str] = None,
226 retry: OptionalRetry = gapic_v1.method.DEFAULT,
227 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
228 metadata: Sequence[Tuple[str, str]] = (),
229 ) -> folders.Folder:
230 r"""Retrieves a folder identified by the supplied resource name.
231 Valid folder resource names have the format
232 ``folders/{folder_id}`` (for example, ``folders/1234``). The
233 caller must have ``resourcemanager.folders.get`` permission on
234 the identified folder.
236 .. code-block:: python
238 # This snippet has been automatically generated and should be regarded as a
239 # code template only.
240 # It will require modifications to work:
241 # - It may require correct/in-range values for request initialization.
242 # - It may require specifying regional endpoints when creating the service
243 # client as shown in:
244 # https://googleapis.dev/python/google-api-core/latest/client_options.html
245 from google.cloud import resourcemanager_v3
247 async def sample_get_folder():
248 # Create a client
249 client = resourcemanager_v3.FoldersAsyncClient()
251 # Initialize request argument(s)
252 request = resourcemanager_v3.GetFolderRequest(
253 name="name_value",
254 )
256 # Make the request
257 response = await client.get_folder(request=request)
259 # Handle the response
260 print(response)
262 Args:
263 request (Optional[Union[google.cloud.resourcemanager_v3.types.GetFolderRequest, dict]]):
264 The request object. The GetFolder request message.
265 name (:class:`str`):
266 Required. The resource name of the folder to retrieve.
267 Must be of the form ``folders/{folder_id}``.
269 This corresponds to the ``name`` field
270 on the ``request`` instance; if ``request`` is provided, this
271 should not be set.
272 retry (google.api_core.retry.Retry): Designation of what errors, if any,
273 should be retried.
274 timeout (float): The timeout for this request.
275 metadata (Sequence[Tuple[str, str]]): Strings which should be
276 sent along with the request as metadata.
278 Returns:
279 google.cloud.resourcemanager_v3.types.Folder:
280 A folder in an organization's
281 resource hierarchy, used to organize
282 that organization's resources.
284 """
285 # Create or coerce a protobuf request object.
286 # Quick check: If we got a request object, we should *not* have
287 # gotten any keyword arguments that map to the request.
288 has_flattened_params = any([name])
289 if request is not None and has_flattened_params:
290 raise ValueError(
291 "If the `request` argument is set, then none of "
292 "the individual field arguments should be set."
293 )
295 request = folders.GetFolderRequest(request)
297 # If we have keyword arguments corresponding to fields on the
298 # request, apply these.
299 if name is not None:
300 request.name = name
302 # Wrap the RPC method; this adds retry and timeout information,
303 # and friendly error handling.
304 rpc = gapic_v1.method_async.wrap_method(
305 self._client._transport.get_folder,
306 default_retry=retries.Retry(
307 initial=0.1,
308 maximum=60.0,
309 multiplier=1.3,
310 predicate=retries.if_exception_type(
311 core_exceptions.ServiceUnavailable,
312 ),
313 deadline=60.0,
314 ),
315 default_timeout=60.0,
316 client_info=DEFAULT_CLIENT_INFO,
317 )
319 # Certain fields should be provided within the metadata header;
320 # add these here.
321 metadata = tuple(metadata) + (
322 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
323 )
325 # Send the request.
326 response = await rpc(
327 request,
328 retry=retry,
329 timeout=timeout,
330 metadata=metadata,
331 )
333 # Done; return the response.
334 return response
336 async def list_folders(
337 self,
338 request: Optional[Union[folders.ListFoldersRequest, dict]] = None,
339 *,
340 parent: Optional[str] = None,
341 retry: OptionalRetry = gapic_v1.method.DEFAULT,
342 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
343 metadata: Sequence[Tuple[str, str]] = (),
344 ) -> pagers.ListFoldersAsyncPager:
345 r"""Lists the folders that are direct descendants of supplied parent
346 resource. ``list()`` provides a strongly consistent view of the
347 folders underneath the specified parent resource. ``list()``
348 returns folders sorted based upon the (ascending) lexical
349 ordering of their display_name. The caller must have
350 ``resourcemanager.folders.list`` permission on the identified
351 parent.
353 .. code-block:: python
355 # This snippet has been automatically generated and should be regarded as a
356 # code template only.
357 # It will require modifications to work:
358 # - It may require correct/in-range values for request initialization.
359 # - It may require specifying regional endpoints when creating the service
360 # client as shown in:
361 # https://googleapis.dev/python/google-api-core/latest/client_options.html
362 from google.cloud import resourcemanager_v3
364 async def sample_list_folders():
365 # Create a client
366 client = resourcemanager_v3.FoldersAsyncClient()
368 # Initialize request argument(s)
369 request = resourcemanager_v3.ListFoldersRequest(
370 parent="parent_value",
371 )
373 # Make the request
374 page_result = client.list_folders(request=request)
376 # Handle the response
377 async for response in page_result:
378 print(response)
380 Args:
381 request (Optional[Union[google.cloud.resourcemanager_v3.types.ListFoldersRequest, dict]]):
382 The request object. The ListFolders request message.
383 parent (:class:`str`):
384 Required. The name of the parent resource whose folders
385 are being listed. Only children of this parent resource
386 are listed; descendants are not listed.
388 If the parent is a folder, use the value
389 ``folders/{folder_id}``. If the parent is an
390 organization, use the value ``organizations/{org_id}``.
392 Access to this method is controlled by checking the
393 ``resourcemanager.folders.list`` permission on the
394 ``parent``.
396 This corresponds to the ``parent`` field
397 on the ``request`` instance; if ``request`` is provided, this
398 should not be set.
399 retry (google.api_core.retry.Retry): Designation of what errors, if any,
400 should be retried.
401 timeout (float): The timeout for this request.
402 metadata (Sequence[Tuple[str, str]]): Strings which should be
403 sent along with the request as metadata.
405 Returns:
406 google.cloud.resourcemanager_v3.services.folders.pagers.ListFoldersAsyncPager:
407 The ListFolders response message.
408 Iterating over this object will yield
409 results and resolve additional pages
410 automatically.
412 """
413 # Create or coerce a protobuf request object.
414 # Quick check: If we got a request object, we should *not* have
415 # gotten any keyword arguments that map to the request.
416 has_flattened_params = any([parent])
417 if request is not None and has_flattened_params:
418 raise ValueError(
419 "If the `request` argument is set, then none of "
420 "the individual field arguments should be set."
421 )
423 request = folders.ListFoldersRequest(request)
425 # If we have keyword arguments corresponding to fields on the
426 # request, apply these.
427 if parent is not None:
428 request.parent = parent
430 # Wrap the RPC method; this adds retry and timeout information,
431 # and friendly error handling.
432 rpc = gapic_v1.method_async.wrap_method(
433 self._client._transport.list_folders,
434 default_retry=retries.Retry(
435 initial=0.1,
436 maximum=60.0,
437 multiplier=1.3,
438 predicate=retries.if_exception_type(
439 core_exceptions.ServiceUnavailable,
440 ),
441 deadline=60.0,
442 ),
443 default_timeout=60.0,
444 client_info=DEFAULT_CLIENT_INFO,
445 )
447 # Send the request.
448 response = await rpc(
449 request,
450 retry=retry,
451 timeout=timeout,
452 metadata=metadata,
453 )
455 # This method is paged; wrap the response in a pager, which provides
456 # an `__aiter__` convenience method.
457 response = pagers.ListFoldersAsyncPager(
458 method=rpc,
459 request=request,
460 response=response,
461 metadata=metadata,
462 )
464 # Done; return the response.
465 return response
467 async def search_folders(
468 self,
469 request: Optional[Union[folders.SearchFoldersRequest, dict]] = None,
470 *,
471 query: Optional[str] = None,
472 retry: OptionalRetry = gapic_v1.method.DEFAULT,
473 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
474 metadata: Sequence[Tuple[str, str]] = (),
475 ) -> pagers.SearchFoldersAsyncPager:
476 r"""Search for folders that match specific filter criteria.
477 ``search()`` provides an eventually consistent view of the
478 folders a user has access to which meet the specified filter
479 criteria.
481 This will only return folders on which the caller has the
482 permission ``resourcemanager.folders.get``.
484 .. code-block:: python
486 # This snippet has been automatically generated and should be regarded as a
487 # code template only.
488 # It will require modifications to work:
489 # - It may require correct/in-range values for request initialization.
490 # - It may require specifying regional endpoints when creating the service
491 # client as shown in:
492 # https://googleapis.dev/python/google-api-core/latest/client_options.html
493 from google.cloud import resourcemanager_v3
495 async def sample_search_folders():
496 # Create a client
497 client = resourcemanager_v3.FoldersAsyncClient()
499 # Initialize request argument(s)
500 request = resourcemanager_v3.SearchFoldersRequest(
501 )
503 # Make the request
504 page_result = client.search_folders(request=request)
506 # Handle the response
507 async for response in page_result:
508 print(response)
510 Args:
511 request (Optional[Union[google.cloud.resourcemanager_v3.types.SearchFoldersRequest, dict]]):
512 The request object. The request message for searching
513 folders.
514 query (:class:`str`):
515 Optional. Search criteria used to select the folders to
516 return. If no search criteria is specified then all
517 accessible folders will be returned.
519 Query expressions can be used to restrict results based
520 upon displayName, state and parent, where the operators
521 ``=`` (``:``) ``NOT``, ``AND`` and ``OR`` can be used
522 along with the suffix wildcard symbol ``*``.
524 The ``displayName`` field in a query expression should
525 use escaped quotes for values that include whitespace to
526 prevent unexpected behavior.
528 ::
530 | Field | Description |
531 |-------------------------|----------------------------------------|
532 | displayName | Filters by displayName. |
533 | parent | Filters by parent (for example: folders/123). |
534 | state, lifecycleState | Filters by state. |
536 Some example queries are:
538 - Query ``displayName=Test*`` returns Folder resources
539 whose display name starts with "Test".
540 - Query ``state=ACTIVE`` returns Folder resources with
541 ``state`` set to ``ACTIVE``.
542 - Query ``parent=folders/123`` returns Folder resources
543 that have ``folders/123`` as a parent resource.
544 - Query ``parent=folders/123 AND state=ACTIVE`` returns
545 active Folder resources that have ``folders/123`` as
546 a parent resource.
547 - Query ``displayName=\\"Test String\\"`` returns
548 Folder resources with display names that include both
549 "Test" and "String".
551 This corresponds to the ``query`` field
552 on the ``request`` instance; if ``request`` is provided, this
553 should not be set.
554 retry (google.api_core.retry.Retry): Designation of what errors, if any,
555 should be retried.
556 timeout (float): The timeout for this request.
557 metadata (Sequence[Tuple[str, str]]): Strings which should be
558 sent along with the request as metadata.
560 Returns:
561 google.cloud.resourcemanager_v3.services.folders.pagers.SearchFoldersAsyncPager:
562 The response message for searching
563 folders.
564 Iterating over this object will yield
565 results and resolve additional pages
566 automatically.
568 """
569 # Create or coerce a protobuf request object.
570 # Quick check: If we got a request object, we should *not* have
571 # gotten any keyword arguments that map to the request.
572 has_flattened_params = any([query])
573 if request is not None and has_flattened_params:
574 raise ValueError(
575 "If the `request` argument is set, then none of "
576 "the individual field arguments should be set."
577 )
579 request = folders.SearchFoldersRequest(request)
581 # If we have keyword arguments corresponding to fields on the
582 # request, apply these.
583 if query is not None:
584 request.query = query
586 # Wrap the RPC method; this adds retry and timeout information,
587 # and friendly error handling.
588 rpc = gapic_v1.method_async.wrap_method(
589 self._client._transport.search_folders,
590 default_timeout=60.0,
591 client_info=DEFAULT_CLIENT_INFO,
592 )
594 # Send the request.
595 response = await rpc(
596 request,
597 retry=retry,
598 timeout=timeout,
599 metadata=metadata,
600 )
602 # This method is paged; wrap the response in a pager, which provides
603 # an `__aiter__` convenience method.
604 response = pagers.SearchFoldersAsyncPager(
605 method=rpc,
606 request=request,
607 response=response,
608 metadata=metadata,
609 )
611 # Done; return the response.
612 return response
614 async def create_folder(
615 self,
616 request: Optional[Union[folders.CreateFolderRequest, dict]] = None,
617 *,
618 folder: Optional[folders.Folder] = None,
619 retry: OptionalRetry = gapic_v1.method.DEFAULT,
620 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
621 metadata: Sequence[Tuple[str, str]] = (),
622 ) -> operation_async.AsyncOperation:
623 r"""Creates a folder in the resource hierarchy. Returns an
624 ``Operation`` which can be used to track the progress of the
625 folder creation workflow. Upon success, the
626 ``Operation.response`` field will be populated with the created
627 Folder.
629 In order to succeed, the addition of this new folder must not
630 violate the folder naming, height, or fanout constraints.
632 - The folder's ``display_name`` must be distinct from all other
633 folders that share its parent.
634 - The addition of the folder must not cause the active folder
635 hierarchy to exceed a height of 10. Note, the full active +
636 deleted folder hierarchy is allowed to reach a height of 20;
637 this provides additional headroom when moving folders that
638 contain deleted folders.
639 - The addition of the folder must not cause the total number of
640 folders under its parent to exceed 300.
642 If the operation fails due to a folder constraint violation,
643 some errors may be returned by the ``CreateFolder`` request,
644 with status code ``FAILED_PRECONDITION`` and an error
645 description. Other folder constraint violations will be
646 communicated in the ``Operation``, with the specific
647 ``PreconditionFailure`` returned in the details list in the
648 ``Operation.error`` field.
650 The caller must have ``resourcemanager.folders.create``
651 permission on the identified parent.
653 .. code-block:: python
655 # This snippet has been automatically generated and should be regarded as a
656 # code template only.
657 # It will require modifications to work:
658 # - It may require correct/in-range values for request initialization.
659 # - It may require specifying regional endpoints when creating the service
660 # client as shown in:
661 # https://googleapis.dev/python/google-api-core/latest/client_options.html
662 from google.cloud import resourcemanager_v3
664 async def sample_create_folder():
665 # Create a client
666 client = resourcemanager_v3.FoldersAsyncClient()
668 # Initialize request argument(s)
669 folder = resourcemanager_v3.Folder()
670 folder.parent = "parent_value"
672 request = resourcemanager_v3.CreateFolderRequest(
673 folder=folder,
674 )
676 # Make the request
677 operation = client.create_folder(request=request)
679 print("Waiting for operation to complete...")
681 response = (await operation).result()
683 # Handle the response
684 print(response)
686 Args:
687 request (Optional[Union[google.cloud.resourcemanager_v3.types.CreateFolderRequest, dict]]):
688 The request object. The CreateFolder request message.
689 folder (:class:`google.cloud.resourcemanager_v3.types.Folder`):
690 Required. The folder being created,
691 only the display name and parent will be
692 consulted. All other fields will be
693 ignored.
695 This corresponds to the ``folder`` field
696 on the ``request`` instance; if ``request`` is provided, this
697 should not be set.
698 retry (google.api_core.retry.Retry): Designation of what errors, if any,
699 should be retried.
700 timeout (float): The timeout for this request.
701 metadata (Sequence[Tuple[str, str]]): Strings which should be
702 sent along with the request as metadata.
704 Returns:
705 google.api_core.operation_async.AsyncOperation:
706 An object representing a long-running operation.
708 The result type for the operation will be :class:`google.cloud.resourcemanager_v3.types.Folder` A folder in an organization's resource hierarchy, used to
709 organize that organization's resources.
711 """
712 # Create or coerce a protobuf request object.
713 # Quick check: If we got a request object, we should *not* have
714 # gotten any keyword arguments that map to the request.
715 has_flattened_params = any([folder])
716 if request is not None and has_flattened_params:
717 raise ValueError(
718 "If the `request` argument is set, then none of "
719 "the individual field arguments should be set."
720 )
722 request = folders.CreateFolderRequest(request)
724 # If we have keyword arguments corresponding to fields on the
725 # request, apply these.
726 if folder is not None:
727 request.folder = folder
729 # Wrap the RPC method; this adds retry and timeout information,
730 # and friendly error handling.
731 rpc = gapic_v1.method_async.wrap_method(
732 self._client._transport.create_folder,
733 default_timeout=60.0,
734 client_info=DEFAULT_CLIENT_INFO,
735 )
737 # Send the request.
738 response = await rpc(
739 request,
740 retry=retry,
741 timeout=timeout,
742 metadata=metadata,
743 )
745 # Wrap the response in an operation future.
746 response = operation_async.from_gapic(
747 response,
748 self._client._transport.operations_client,
749 folders.Folder,
750 metadata_type=folders.CreateFolderMetadata,
751 )
753 # Done; return the response.
754 return response
756 async def update_folder(
757 self,
758 request: Optional[Union[folders.UpdateFolderRequest, dict]] = None,
759 *,
760 folder: Optional[folders.Folder] = None,
761 update_mask: Optional[field_mask_pb2.FieldMask] = None,
762 retry: OptionalRetry = gapic_v1.method.DEFAULT,
763 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
764 metadata: Sequence[Tuple[str, str]] = (),
765 ) -> operation_async.AsyncOperation:
766 r"""Updates a folder, changing its ``display_name``. Changes to the
767 folder ``display_name`` will be rejected if they violate either
768 the ``display_name`` formatting rules or the naming constraints
769 described in the
770 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
771 documentation.
773 The folder's ``display_name`` must start and end with a letter
774 or digit, may contain letters, digits, spaces, hyphens and
775 underscores and can be between 3 and 30 characters. This is
776 captured by the regular expression:
777 ``[\p{L}\p{N}][\p{L}\p{N}_- ]{1,28}[\p{L}\p{N}]``. The caller
778 must have ``resourcemanager.folders.update`` permission on the
779 identified folder.
781 If the update fails due to the unique name constraint then a
782 ``PreconditionFailure`` explaining this violation will be
783 returned in the Status.details field.
785 .. code-block:: python
787 # This snippet has been automatically generated and should be regarded as a
788 # code template only.
789 # It will require modifications to work:
790 # - It may require correct/in-range values for request initialization.
791 # - It may require specifying regional endpoints when creating the service
792 # client as shown in:
793 # https://googleapis.dev/python/google-api-core/latest/client_options.html
794 from google.cloud import resourcemanager_v3
796 async def sample_update_folder():
797 # Create a client
798 client = resourcemanager_v3.FoldersAsyncClient()
800 # Initialize request argument(s)
801 folder = resourcemanager_v3.Folder()
802 folder.parent = "parent_value"
804 request = resourcemanager_v3.UpdateFolderRequest(
805 folder=folder,
806 )
808 # Make the request
809 operation = client.update_folder(request=request)
811 print("Waiting for operation to complete...")
813 response = (await operation).result()
815 # Handle the response
816 print(response)
818 Args:
819 request (Optional[Union[google.cloud.resourcemanager_v3.types.UpdateFolderRequest, dict]]):
820 The request object. The request sent to the
821 [UpdateFolder][google.cloud.resourcemanager.v3.Folder.UpdateFolder]
822 method.
824 Only the ``display_name`` field can be changed. All
825 other fields will be ignored. Use the
826 [MoveFolder][google.cloud.resourcemanager.v3.Folders.MoveFolder]
827 method to change the ``parent`` field.
828 folder (:class:`google.cloud.resourcemanager_v3.types.Folder`):
829 Required. The new definition of the Folder. It must
830 include the ``name`` field, which cannot be changed.
832 This corresponds to the ``folder`` field
833 on the ``request`` instance; if ``request`` is provided, this
834 should not be set.
835 update_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`):
836 Required. Fields to be updated. Only the
837 ``display_name`` can be updated.
839 This corresponds to the ``update_mask`` field
840 on the ``request`` instance; if ``request`` is provided, this
841 should not be set.
842 retry (google.api_core.retry.Retry): Designation of what errors, if any,
843 should be retried.
844 timeout (float): The timeout for this request.
845 metadata (Sequence[Tuple[str, str]]): Strings which should be
846 sent along with the request as metadata.
848 Returns:
849 google.api_core.operation_async.AsyncOperation:
850 An object representing a long-running operation.
852 The result type for the operation will be :class:`google.cloud.resourcemanager_v3.types.Folder` A folder in an organization's resource hierarchy, used to
853 organize that organization's resources.
855 """
856 # Create or coerce a protobuf request object.
857 # Quick check: If we got a request object, we should *not* have
858 # gotten any keyword arguments that map to the request.
859 has_flattened_params = any([folder, update_mask])
860 if request is not None and has_flattened_params:
861 raise ValueError(
862 "If the `request` argument is set, then none of "
863 "the individual field arguments should be set."
864 )
866 request = folders.UpdateFolderRequest(request)
868 # If we have keyword arguments corresponding to fields on the
869 # request, apply these.
870 if folder is not None:
871 request.folder = folder
872 if update_mask is not None:
873 request.update_mask = update_mask
875 # Wrap the RPC method; this adds retry and timeout information,
876 # and friendly error handling.
877 rpc = gapic_v1.method_async.wrap_method(
878 self._client._transport.update_folder,
879 default_timeout=60.0,
880 client_info=DEFAULT_CLIENT_INFO,
881 )
883 # Certain fields should be provided within the metadata header;
884 # add these here.
885 metadata = tuple(metadata) + (
886 gapic_v1.routing_header.to_grpc_metadata(
887 (("folder.name", request.folder.name),)
888 ),
889 )
891 # Send the request.
892 response = await rpc(
893 request,
894 retry=retry,
895 timeout=timeout,
896 metadata=metadata,
897 )
899 # Wrap the response in an operation future.
900 response = operation_async.from_gapic(
901 response,
902 self._client._transport.operations_client,
903 folders.Folder,
904 metadata_type=folders.UpdateFolderMetadata,
905 )
907 # Done; return the response.
908 return response
910 async def move_folder(
911 self,
912 request: Optional[Union[folders.MoveFolderRequest, dict]] = None,
913 *,
914 name: Optional[str] = None,
915 destination_parent: Optional[str] = None,
916 retry: OptionalRetry = gapic_v1.method.DEFAULT,
917 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
918 metadata: Sequence[Tuple[str, str]] = (),
919 ) -> operation_async.AsyncOperation:
920 r"""Moves a folder under a new resource parent. Returns an
921 ``Operation`` which can be used to track the progress of the
922 folder move workflow. Upon success, the ``Operation.response``
923 field will be populated with the moved folder. Upon failure, a
924 ``FolderOperationError`` categorizing the failure cause will be
925 returned - if the failure occurs synchronously then the
926 ``FolderOperationError`` will be returned in the
927 ``Status.details`` field. If it occurs asynchronously, then the
928 FolderOperation will be returned in the ``Operation.error``
929 field. In addition, the ``Operation.metadata`` field will be
930 populated with a ``FolderOperation`` message as an aid to
931 stateless clients. Folder moves will be rejected if they violate
932 either the naming, height, or fanout constraints described in
933 the
934 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
935 documentation. The caller must have
936 ``resourcemanager.folders.move`` permission on the folder's
937 current and proposed new parent.
939 .. code-block:: python
941 # This snippet has been automatically generated and should be regarded as a
942 # code template only.
943 # It will require modifications to work:
944 # - It may require correct/in-range values for request initialization.
945 # - It may require specifying regional endpoints when creating the service
946 # client as shown in:
947 # https://googleapis.dev/python/google-api-core/latest/client_options.html
948 from google.cloud import resourcemanager_v3
950 async def sample_move_folder():
951 # Create a client
952 client = resourcemanager_v3.FoldersAsyncClient()
954 # Initialize request argument(s)
955 request = resourcemanager_v3.MoveFolderRequest(
956 name="name_value",
957 destination_parent="destination_parent_value",
958 )
960 # Make the request
961 operation = client.move_folder(request=request)
963 print("Waiting for operation to complete...")
965 response = (await operation).result()
967 # Handle the response
968 print(response)
970 Args:
971 request (Optional[Union[google.cloud.resourcemanager_v3.types.MoveFolderRequest, dict]]):
972 The request object. The MoveFolder request message.
973 name (:class:`str`):
974 Required. The resource name of the Folder to move. Must
975 be of the form folders/{folder_id}
977 This corresponds to the ``name`` field
978 on the ``request`` instance; if ``request`` is provided, this
979 should not be set.
980 destination_parent (:class:`str`):
981 Required. The resource name of the folder or
982 organization which should be the folder's new parent.
983 Must be of the form ``folders/{folder_id}`` or
984 ``organizations/{org_id}``.
986 This corresponds to the ``destination_parent`` field
987 on the ``request`` instance; if ``request`` is provided, this
988 should not be set.
989 retry (google.api_core.retry.Retry): Designation of what errors, if any,
990 should be retried.
991 timeout (float): The timeout for this request.
992 metadata (Sequence[Tuple[str, str]]): Strings which should be
993 sent along with the request as metadata.
995 Returns:
996 google.api_core.operation_async.AsyncOperation:
997 An object representing a long-running operation.
999 The result type for the operation will be :class:`google.cloud.resourcemanager_v3.types.Folder` A folder in an organization's resource hierarchy, used to
1000 organize that organization's resources.
1002 """
1003 # Create or coerce a protobuf request object.
1004 # Quick check: If we got a request object, we should *not* have
1005 # gotten any keyword arguments that map to the request.
1006 has_flattened_params = any([name, destination_parent])
1007 if request is not None and has_flattened_params:
1008 raise ValueError(
1009 "If the `request` argument is set, then none of "
1010 "the individual field arguments should be set."
1011 )
1013 request = folders.MoveFolderRequest(request)
1015 # If we have keyword arguments corresponding to fields on the
1016 # request, apply these.
1017 if name is not None:
1018 request.name = name
1019 if destination_parent is not None:
1020 request.destination_parent = destination_parent
1022 # Wrap the RPC method; this adds retry and timeout information,
1023 # and friendly error handling.
1024 rpc = gapic_v1.method_async.wrap_method(
1025 self._client._transport.move_folder,
1026 default_timeout=60.0,
1027 client_info=DEFAULT_CLIENT_INFO,
1028 )
1030 # Certain fields should be provided within the metadata header;
1031 # add these here.
1032 metadata = tuple(metadata) + (
1033 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1034 )
1036 # Send the request.
1037 response = await rpc(
1038 request,
1039 retry=retry,
1040 timeout=timeout,
1041 metadata=metadata,
1042 )
1044 # Wrap the response in an operation future.
1045 response = operation_async.from_gapic(
1046 response,
1047 self._client._transport.operations_client,
1048 folders.Folder,
1049 metadata_type=folders.MoveFolderMetadata,
1050 )
1052 # Done; return the response.
1053 return response
1055 async def delete_folder(
1056 self,
1057 request: Optional[Union[folders.DeleteFolderRequest, dict]] = None,
1058 *,
1059 name: Optional[str] = None,
1060 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1061 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1062 metadata: Sequence[Tuple[str, str]] = (),
1063 ) -> operation_async.AsyncOperation:
1064 r"""Requests deletion of a folder. The folder is moved into the
1065 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1066 state immediately, and is deleted approximately 30 days later.
1067 This method may only be called on an empty folder, where a
1068 folder is empty if it doesn't contain any folders or projects in
1069 the
1070 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1071 state. If called on a folder in
1072 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1073 state the operation will result in a no-op success. The caller
1074 must have ``resourcemanager.folders.delete`` permission on the
1075 identified folder.
1077 .. code-block:: python
1079 # This snippet has been automatically generated and should be regarded as a
1080 # code template only.
1081 # It will require modifications to work:
1082 # - It may require correct/in-range values for request initialization.
1083 # - It may require specifying regional endpoints when creating the service
1084 # client as shown in:
1085 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1086 from google.cloud import resourcemanager_v3
1088 async def sample_delete_folder():
1089 # Create a client
1090 client = resourcemanager_v3.FoldersAsyncClient()
1092 # Initialize request argument(s)
1093 request = resourcemanager_v3.DeleteFolderRequest(
1094 name="name_value",
1095 )
1097 # Make the request
1098 operation = client.delete_folder(request=request)
1100 print("Waiting for operation to complete...")
1102 response = (await operation).result()
1104 # Handle the response
1105 print(response)
1107 Args:
1108 request (Optional[Union[google.cloud.resourcemanager_v3.types.DeleteFolderRequest, dict]]):
1109 The request object. The DeleteFolder request message.
1110 name (:class:`str`):
1111 Required. The resource name of the folder to be deleted.
1112 Must be of the form ``folders/{folder_id}``.
1114 This corresponds to the ``name`` field
1115 on the ``request`` instance; if ``request`` is provided, this
1116 should not be set.
1117 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1118 should be retried.
1119 timeout (float): The timeout for this request.
1120 metadata (Sequence[Tuple[str, str]]): Strings which should be
1121 sent along with the request as metadata.
1123 Returns:
1124 google.api_core.operation_async.AsyncOperation:
1125 An object representing a long-running operation.
1127 The result type for the operation will be :class:`google.cloud.resourcemanager_v3.types.Folder` A folder in an organization's resource hierarchy, used to
1128 organize that organization's resources.
1130 """
1131 # Create or coerce a protobuf request object.
1132 # Quick check: If we got a request object, we should *not* have
1133 # gotten any keyword arguments that map to the request.
1134 has_flattened_params = any([name])
1135 if request is not None and has_flattened_params:
1136 raise ValueError(
1137 "If the `request` argument is set, then none of "
1138 "the individual field arguments should be set."
1139 )
1141 request = folders.DeleteFolderRequest(request)
1143 # If we have keyword arguments corresponding to fields on the
1144 # request, apply these.
1145 if name is not None:
1146 request.name = name
1148 # Wrap the RPC method; this adds retry and timeout information,
1149 # and friendly error handling.
1150 rpc = gapic_v1.method_async.wrap_method(
1151 self._client._transport.delete_folder,
1152 default_timeout=60.0,
1153 client_info=DEFAULT_CLIENT_INFO,
1154 )
1156 # Certain fields should be provided within the metadata header;
1157 # add these here.
1158 metadata = tuple(metadata) + (
1159 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1160 )
1162 # Send the request.
1163 response = await rpc(
1164 request,
1165 retry=retry,
1166 timeout=timeout,
1167 metadata=metadata,
1168 )
1170 # Wrap the response in an operation future.
1171 response = operation_async.from_gapic(
1172 response,
1173 self._client._transport.operations_client,
1174 folders.Folder,
1175 metadata_type=folders.DeleteFolderMetadata,
1176 )
1178 # Done; return the response.
1179 return response
1181 async def undelete_folder(
1182 self,
1183 request: Optional[Union[folders.UndeleteFolderRequest, dict]] = None,
1184 *,
1185 name: Optional[str] = None,
1186 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1187 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1188 metadata: Sequence[Tuple[str, str]] = (),
1189 ) -> operation_async.AsyncOperation:
1190 r"""Cancels the deletion request for a folder. This method may be
1191 called on a folder in any state. If the folder is in the
1192 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1193 state the result will be a no-op success. In order to succeed,
1194 the folder's parent must be in the
1195 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1196 state. In addition, reintroducing the folder into the tree must
1197 not violate folder naming, height, and fanout constraints
1198 described in the
1199 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
1200 documentation. The caller must have
1201 ``resourcemanager.folders.undelete`` permission on the
1202 identified folder.
1204 .. code-block:: python
1206 # This snippet has been automatically generated and should be regarded as a
1207 # code template only.
1208 # It will require modifications to work:
1209 # - It may require correct/in-range values for request initialization.
1210 # - It may require specifying regional endpoints when creating the service
1211 # client as shown in:
1212 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1213 from google.cloud import resourcemanager_v3
1215 async def sample_undelete_folder():
1216 # Create a client
1217 client = resourcemanager_v3.FoldersAsyncClient()
1219 # Initialize request argument(s)
1220 request = resourcemanager_v3.UndeleteFolderRequest(
1221 name="name_value",
1222 )
1224 # Make the request
1225 operation = client.undelete_folder(request=request)
1227 print("Waiting for operation to complete...")
1229 response = (await operation).result()
1231 # Handle the response
1232 print(response)
1234 Args:
1235 request (Optional[Union[google.cloud.resourcemanager_v3.types.UndeleteFolderRequest, dict]]):
1236 The request object. The UndeleteFolder request message.
1237 name (:class:`str`):
1238 Required. The resource name of the folder to undelete.
1239 Must be of the form ``folders/{folder_id}``.
1241 This corresponds to the ``name`` field
1242 on the ``request`` instance; if ``request`` is provided, this
1243 should not be set.
1244 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1245 should be retried.
1246 timeout (float): The timeout for this request.
1247 metadata (Sequence[Tuple[str, str]]): Strings which should be
1248 sent along with the request as metadata.
1250 Returns:
1251 google.api_core.operation_async.AsyncOperation:
1252 An object representing a long-running operation.
1254 The result type for the operation will be :class:`google.cloud.resourcemanager_v3.types.Folder` A folder in an organization's resource hierarchy, used to
1255 organize that organization's resources.
1257 """
1258 # Create or coerce a protobuf request object.
1259 # Quick check: If we got a request object, we should *not* have
1260 # gotten any keyword arguments that map to the request.
1261 has_flattened_params = any([name])
1262 if request is not None and has_flattened_params:
1263 raise ValueError(
1264 "If the `request` argument is set, then none of "
1265 "the individual field arguments should be set."
1266 )
1268 request = folders.UndeleteFolderRequest(request)
1270 # If we have keyword arguments corresponding to fields on the
1271 # request, apply these.
1272 if name is not None:
1273 request.name = name
1275 # Wrap the RPC method; this adds retry and timeout information,
1276 # and friendly error handling.
1277 rpc = gapic_v1.method_async.wrap_method(
1278 self._client._transport.undelete_folder,
1279 default_timeout=60.0,
1280 client_info=DEFAULT_CLIENT_INFO,
1281 )
1283 # Certain fields should be provided within the metadata header;
1284 # add these here.
1285 metadata = tuple(metadata) + (
1286 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1287 )
1289 # Send the request.
1290 response = await rpc(
1291 request,
1292 retry=retry,
1293 timeout=timeout,
1294 metadata=metadata,
1295 )
1297 # Wrap the response in an operation future.
1298 response = operation_async.from_gapic(
1299 response,
1300 self._client._transport.operations_client,
1301 folders.Folder,
1302 metadata_type=folders.UndeleteFolderMetadata,
1303 )
1305 # Done; return the response.
1306 return response
1308 async def get_iam_policy(
1309 self,
1310 request: Optional[Union[iam_policy_pb2.GetIamPolicyRequest, dict]] = None,
1311 *,
1312 resource: Optional[str] = None,
1313 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1314 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1315 metadata: Sequence[Tuple[str, str]] = (),
1316 ) -> policy_pb2.Policy:
1317 r"""Gets the access control policy for a folder. The returned policy
1318 may be empty if no such policy or resource exists. The
1319 ``resource`` field should be the folder's resource name, for
1320 example: "folders/1234". The caller must have
1321 ``resourcemanager.folders.getIamPolicy`` permission on the
1322 identified folder.
1324 .. code-block:: python
1326 # This snippet has been automatically generated and should be regarded as a
1327 # code template only.
1328 # It will require modifications to work:
1329 # - It may require correct/in-range values for request initialization.
1330 # - It may require specifying regional endpoints when creating the service
1331 # client as shown in:
1332 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1333 from google.cloud import resourcemanager_v3
1334 from google.iam.v1 import iam_policy_pb2 # type: ignore
1336 async def sample_get_iam_policy():
1337 # Create a client
1338 client = resourcemanager_v3.FoldersAsyncClient()
1340 # Initialize request argument(s)
1341 request = iam_policy_pb2.GetIamPolicyRequest(
1342 resource="resource_value",
1343 )
1345 # Make the request
1346 response = await client.get_iam_policy(request=request)
1348 # Handle the response
1349 print(response)
1351 Args:
1352 request (Optional[Union[google.iam.v1.iam_policy_pb2.GetIamPolicyRequest, dict]]):
1353 The request object. Request message for ``GetIamPolicy`` method.
1354 resource (:class:`str`):
1355 REQUIRED: The resource for which the
1356 policy is being requested. See the
1357 operation documentation for the
1358 appropriate value for this field.
1360 This corresponds to the ``resource`` field
1361 on the ``request`` instance; if ``request`` is provided, this
1362 should not be set.
1363 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1364 should be retried.
1365 timeout (float): The timeout for this request.
1366 metadata (Sequence[Tuple[str, str]]): Strings which should be
1367 sent along with the request as metadata.
1369 Returns:
1370 google.iam.v1.policy_pb2.Policy:
1371 An Identity and Access Management (IAM) policy, which specifies access
1372 controls for Google Cloud resources.
1374 A Policy is a collection of bindings. A binding binds
1375 one or more members, or principals, to a single role.
1376 Principals can be user accounts, service accounts,
1377 Google groups, and domains (such as G Suite). A role
1378 is a named list of permissions; each role can be an
1379 IAM predefined role or a user-created custom role.
1381 For some types of Google Cloud resources, a binding
1382 can also specify a condition, which is a logical
1383 expression that allows access to a resource only if
1384 the expression evaluates to true. A condition can add
1385 constraints based on attributes of the request, the
1386 resource, or both. To learn which resources support
1387 conditions in their IAM policies, see the [IAM
1388 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1390 **JSON example:**
1392 {
1393 "bindings": [
1394 {
1395 "role":
1396 "roles/resourcemanager.organizationAdmin",
1397 "members": [ "user:mike@example.com",
1398 "group:admins@example.com",
1399 "domain:google.com",
1400 "serviceAccount:my-project-id@appspot.gserviceaccount.com"
1401 ]
1403 }, { "role":
1404 "roles/resourcemanager.organizationViewer",
1405 "members": [ "user:eve@example.com" ],
1406 "condition": { "title": "expirable access",
1407 "description": "Does not grant access after
1408 Sep 2020", "expression": "request.time <
1409 timestamp('2020-10-01T00:00:00.000Z')", } }
1411 ], "etag": "BwWWja0YfJA=", "version": 3
1413 }
1415 **YAML example:**
1417 bindings: - members: - user:\ mike@example.com -
1418 group:\ admins@example.com - domain:google.com -
1419 serviceAccount:\ my-project-id@appspot.gserviceaccount.com
1420 role: roles/resourcemanager.organizationAdmin -
1421 members: - user:\ eve@example.com role:
1422 roles/resourcemanager.organizationViewer
1423 condition: title: expirable access description:
1424 Does not grant access after Sep 2020 expression:
1425 request.time <
1426 timestamp('2020-10-01T00:00:00.000Z') etag:
1427 BwWWja0YfJA= version: 3
1429 For a description of IAM and its features, see the
1430 [IAM
1431 documentation](\ https://cloud.google.com/iam/docs/).
1433 """
1434 # Create or coerce a protobuf request object.
1435 # Quick check: If we got a request object, we should *not* have
1436 # gotten any keyword arguments that map to the request.
1437 has_flattened_params = any([resource])
1438 if request is not None and has_flattened_params:
1439 raise ValueError(
1440 "If the `request` argument is set, then none of "
1441 "the individual field arguments should be set."
1442 )
1444 # The request isn't a proto-plus wrapped type,
1445 # so it must be constructed via keyword expansion.
1446 if isinstance(request, dict):
1447 request = iam_policy_pb2.GetIamPolicyRequest(**request)
1448 elif not request:
1449 request = iam_policy_pb2.GetIamPolicyRequest(
1450 resource=resource,
1451 )
1453 # Wrap the RPC method; this adds retry and timeout information,
1454 # and friendly error handling.
1455 rpc = gapic_v1.method_async.wrap_method(
1456 self._client._transport.get_iam_policy,
1457 default_retry=retries.Retry(
1458 initial=0.1,
1459 maximum=60.0,
1460 multiplier=1.3,
1461 predicate=retries.if_exception_type(
1462 core_exceptions.ServiceUnavailable,
1463 ),
1464 deadline=60.0,
1465 ),
1466 default_timeout=60.0,
1467 client_info=DEFAULT_CLIENT_INFO,
1468 )
1470 # Certain fields should be provided within the metadata header;
1471 # add these here.
1472 metadata = tuple(metadata) + (
1473 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1474 )
1476 # Send the request.
1477 response = await rpc(
1478 request,
1479 retry=retry,
1480 timeout=timeout,
1481 metadata=metadata,
1482 )
1484 # Done; return the response.
1485 return response
1487 async def set_iam_policy(
1488 self,
1489 request: Optional[Union[iam_policy_pb2.SetIamPolicyRequest, dict]] = None,
1490 *,
1491 resource: Optional[str] = None,
1492 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1493 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1494 metadata: Sequence[Tuple[str, str]] = (),
1495 ) -> policy_pb2.Policy:
1496 r"""Sets the access control policy on a folder, replacing any
1497 existing policy. The ``resource`` field should be the folder's
1498 resource name, for example: "folders/1234". The caller must have
1499 ``resourcemanager.folders.setIamPolicy`` permission on the
1500 identified folder.
1502 .. code-block:: python
1504 # This snippet has been automatically generated and should be regarded as a
1505 # code template only.
1506 # It will require modifications to work:
1507 # - It may require correct/in-range values for request initialization.
1508 # - It may require specifying regional endpoints when creating the service
1509 # client as shown in:
1510 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1511 from google.cloud import resourcemanager_v3
1512 from google.iam.v1 import iam_policy_pb2 # type: ignore
1514 async def sample_set_iam_policy():
1515 # Create a client
1516 client = resourcemanager_v3.FoldersAsyncClient()
1518 # Initialize request argument(s)
1519 request = iam_policy_pb2.SetIamPolicyRequest(
1520 resource="resource_value",
1521 )
1523 # Make the request
1524 response = await client.set_iam_policy(request=request)
1526 # Handle the response
1527 print(response)
1529 Args:
1530 request (Optional[Union[google.iam.v1.iam_policy_pb2.SetIamPolicyRequest, dict]]):
1531 The request object. Request message for ``SetIamPolicy`` method.
1532 resource (:class:`str`):
1533 REQUIRED: The resource for which the
1534 policy is being specified. See the
1535 operation documentation for the
1536 appropriate value for this field.
1538 This corresponds to the ``resource`` field
1539 on the ``request`` instance; if ``request`` is provided, this
1540 should not be set.
1541 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1542 should be retried.
1543 timeout (float): The timeout for this request.
1544 metadata (Sequence[Tuple[str, str]]): Strings which should be
1545 sent along with the request as metadata.
1547 Returns:
1548 google.iam.v1.policy_pb2.Policy:
1549 An Identity and Access Management (IAM) policy, which specifies access
1550 controls for Google Cloud resources.
1552 A Policy is a collection of bindings. A binding binds
1553 one or more members, or principals, to a single role.
1554 Principals can be user accounts, service accounts,
1555 Google groups, and domains (such as G Suite). A role
1556 is a named list of permissions; each role can be an
1557 IAM predefined role or a user-created custom role.
1559 For some types of Google Cloud resources, a binding
1560 can also specify a condition, which is a logical
1561 expression that allows access to a resource only if
1562 the expression evaluates to true. A condition can add
1563 constraints based on attributes of the request, the
1564 resource, or both. To learn which resources support
1565 conditions in their IAM policies, see the [IAM
1566 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1568 **JSON example:**
1570 {
1571 "bindings": [
1572 {
1573 "role":
1574 "roles/resourcemanager.organizationAdmin",
1575 "members": [ "user:mike@example.com",
1576 "group:admins@example.com",
1577 "domain:google.com",
1578 "serviceAccount:my-project-id@appspot.gserviceaccount.com"
1579 ]
1581 }, { "role":
1582 "roles/resourcemanager.organizationViewer",
1583 "members": [ "user:eve@example.com" ],
1584 "condition": { "title": "expirable access",
1585 "description": "Does not grant access after
1586 Sep 2020", "expression": "request.time <
1587 timestamp('2020-10-01T00:00:00.000Z')", } }
1589 ], "etag": "BwWWja0YfJA=", "version": 3
1591 }
1593 **YAML example:**
1595 bindings: - members: - user:\ mike@example.com -
1596 group:\ admins@example.com - domain:google.com -
1597 serviceAccount:\ my-project-id@appspot.gserviceaccount.com
1598 role: roles/resourcemanager.organizationAdmin -
1599 members: - user:\ eve@example.com role:
1600 roles/resourcemanager.organizationViewer
1601 condition: title: expirable access description:
1602 Does not grant access after Sep 2020 expression:
1603 request.time <
1604 timestamp('2020-10-01T00:00:00.000Z') etag:
1605 BwWWja0YfJA= version: 3
1607 For a description of IAM and its features, see the
1608 [IAM
1609 documentation](\ https://cloud.google.com/iam/docs/).
1611 """
1612 # Create or coerce a protobuf request object.
1613 # Quick check: If we got a request object, we should *not* have
1614 # gotten any keyword arguments that map to the request.
1615 has_flattened_params = any([resource])
1616 if request is not None and has_flattened_params:
1617 raise ValueError(
1618 "If the `request` argument is set, then none of "
1619 "the individual field arguments should be set."
1620 )
1622 # The request isn't a proto-plus wrapped type,
1623 # so it must be constructed via keyword expansion.
1624 if isinstance(request, dict):
1625 request = iam_policy_pb2.SetIamPolicyRequest(**request)
1626 elif not request:
1627 request = iam_policy_pb2.SetIamPolicyRequest(
1628 resource=resource,
1629 )
1631 # Wrap the RPC method; this adds retry and timeout information,
1632 # and friendly error handling.
1633 rpc = gapic_v1.method_async.wrap_method(
1634 self._client._transport.set_iam_policy,
1635 default_timeout=60.0,
1636 client_info=DEFAULT_CLIENT_INFO,
1637 )
1639 # Certain fields should be provided within the metadata header;
1640 # add these here.
1641 metadata = tuple(metadata) + (
1642 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1643 )
1645 # Send the request.
1646 response = await rpc(
1647 request,
1648 retry=retry,
1649 timeout=timeout,
1650 metadata=metadata,
1651 )
1653 # Done; return the response.
1654 return response
1656 async def test_iam_permissions(
1657 self,
1658 request: Optional[Union[iam_policy_pb2.TestIamPermissionsRequest, dict]] = None,
1659 *,
1660 resource: Optional[str] = None,
1661 permissions: Optional[MutableSequence[str]] = None,
1662 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1663 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1664 metadata: Sequence[Tuple[str, str]] = (),
1665 ) -> iam_policy_pb2.TestIamPermissionsResponse:
1666 r"""Returns permissions that a caller has on the specified folder.
1667 The ``resource`` field should be the folder's resource name, for
1668 example: "folders/1234".
1670 There are no permissions required for making this API call.
1672 .. code-block:: python
1674 # This snippet has been automatically generated and should be regarded as a
1675 # code template only.
1676 # It will require modifications to work:
1677 # - It may require correct/in-range values for request initialization.
1678 # - It may require specifying regional endpoints when creating the service
1679 # client as shown in:
1680 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1681 from google.cloud import resourcemanager_v3
1682 from google.iam.v1 import iam_policy_pb2 # type: ignore
1684 async def sample_test_iam_permissions():
1685 # Create a client
1686 client = resourcemanager_v3.FoldersAsyncClient()
1688 # Initialize request argument(s)
1689 request = iam_policy_pb2.TestIamPermissionsRequest(
1690 resource="resource_value",
1691 permissions=['permissions_value1', 'permissions_value2'],
1692 )
1694 # Make the request
1695 response = await client.test_iam_permissions(request=request)
1697 # Handle the response
1698 print(response)
1700 Args:
1701 request (Optional[Union[google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest, dict]]):
1702 The request object. Request message for ``TestIamPermissions`` method.
1703 resource (:class:`str`):
1704 REQUIRED: The resource for which the
1705 policy detail is being requested. See
1706 the operation documentation for the
1707 appropriate value for this field.
1709 This corresponds to the ``resource`` field
1710 on the ``request`` instance; if ``request`` is provided, this
1711 should not be set.
1712 permissions (:class:`MutableSequence[str]`):
1713 The set of permissions to check for the ``resource``.
1714 Permissions with wildcards (such as '*' or 'storage.*')
1715 are not allowed. For more information see `IAM
1716 Overview <https://cloud.google.com/iam/docs/overview#permissions>`__.
1718 This corresponds to the ``permissions`` field
1719 on the ``request`` instance; if ``request`` is provided, this
1720 should not be set.
1721 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1722 should be retried.
1723 timeout (float): The timeout for this request.
1724 metadata (Sequence[Tuple[str, str]]): Strings which should be
1725 sent along with the request as metadata.
1727 Returns:
1728 google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse:
1729 Response message for TestIamPermissions method.
1730 """
1731 # Create or coerce a protobuf request object.
1732 # Quick check: If we got a request object, we should *not* have
1733 # gotten any keyword arguments that map to the request.
1734 has_flattened_params = any([resource, permissions])
1735 if request is not None and has_flattened_params:
1736 raise ValueError(
1737 "If the `request` argument is set, then none of "
1738 "the individual field arguments should be set."
1739 )
1741 # The request isn't a proto-plus wrapped type,
1742 # so it must be constructed via keyword expansion.
1743 if isinstance(request, dict):
1744 request = iam_policy_pb2.TestIamPermissionsRequest(**request)
1745 elif not request:
1746 request = iam_policy_pb2.TestIamPermissionsRequest(
1747 resource=resource,
1748 permissions=permissions,
1749 )
1751 # Wrap the RPC method; this adds retry and timeout information,
1752 # and friendly error handling.
1753 rpc = gapic_v1.method_async.wrap_method(
1754 self._client._transport.test_iam_permissions,
1755 default_timeout=None,
1756 client_info=DEFAULT_CLIENT_INFO,
1757 )
1759 # Certain fields should be provided within the metadata header;
1760 # add these here.
1761 metadata = tuple(metadata) + (
1762 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1763 )
1765 # Send the request.
1766 response = await rpc(
1767 request,
1768 retry=retry,
1769 timeout=timeout,
1770 metadata=metadata,
1771 )
1773 # Done; return the response.
1774 return response
1776 async def get_operation(
1777 self,
1778 request: Optional[operations_pb2.GetOperationRequest] = None,
1779 *,
1780 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1781 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1782 metadata: Sequence[Tuple[str, str]] = (),
1783 ) -> operations_pb2.Operation:
1784 r"""Gets the latest state of a long-running operation.
1786 Args:
1787 request (:class:`~.operations_pb2.GetOperationRequest`):
1788 The request object. Request message for
1789 `GetOperation` method.
1790 retry (google.api_core.retry.Retry): Designation of what errors,
1791 if any, should be retried.
1792 timeout (float): The timeout for this request.
1793 metadata (Sequence[Tuple[str, str]]): Strings which should be
1794 sent along with the request as metadata.
1795 Returns:
1796 ~.operations_pb2.Operation:
1797 An ``Operation`` object.
1798 """
1799 # Create or coerce a protobuf request object.
1800 # The request isn't a proto-plus wrapped type,
1801 # so it must be constructed via keyword expansion.
1802 if isinstance(request, dict):
1803 request = operations_pb2.GetOperationRequest(**request)
1805 # Wrap the RPC method; this adds retry and timeout information,
1806 # and friendly error handling.
1807 rpc = gapic_v1.method.wrap_method(
1808 self._client._transport.get_operation,
1809 default_timeout=None,
1810 client_info=DEFAULT_CLIENT_INFO,
1811 )
1813 # Certain fields should be provided within the metadata header;
1814 # add these here.
1815 metadata = tuple(metadata) + (
1816 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1817 )
1819 # Send the request.
1820 response = await rpc(
1821 request,
1822 retry=retry,
1823 timeout=timeout,
1824 metadata=metadata,
1825 )
1827 # Done; return the response.
1828 return response
1830 async def __aenter__(self):
1831 return self
1833 async def __aexit__(self, exc_type, exc, tb):
1834 await self.transport.close()
1837DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
1838 gapic_version=package_version.__version__
1839)
1842__all__ = ("FoldersAsyncClient",)