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# -*- coding: utf-8 -*-
2# Copyright 2025 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 logging as std_logging
18import re
19from typing import (
20 Callable,
21 Dict,
22 Mapping,
23 MutableMapping,
24 MutableSequence,
25 Optional,
26 Sequence,
27 Tuple,
28 Type,
29 Union,
30)
32from google.api_core import exceptions as core_exceptions
33from google.api_core import gapic_v1
34from google.api_core import retry_async as retries
35from google.api_core.client_options import ClientOptions
36from google.auth import credentials as ga_credentials # type: ignore
37from google.oauth2 import service_account # type: ignore
38import google.protobuf
40from google.cloud.resourcemanager_v3 import gapic_version as package_version
42try:
43 OptionalRetry = Union[retries.AsyncRetry, gapic_v1.method._MethodDefault, None]
44except AttributeError: # pragma: NO COVER
45 OptionalRetry = Union[retries.AsyncRetry, object, None] # type: ignore
47from google.api_core import operation # type: ignore
48from google.api_core import operation_async # type: ignore
49from google.iam.v1 import iam_policy_pb2 # type: ignore
50from google.iam.v1 import policy_pb2 # type: ignore
51from google.longrunning import operations_pb2 # type: ignore
52from google.protobuf import field_mask_pb2 # type: ignore
53from google.protobuf import timestamp_pb2 # type: ignore
55from google.cloud.resourcemanager_v3.services.folders import pagers
56from google.cloud.resourcemanager_v3.types import folders
58from .client import FoldersClient
59from .transports.base import DEFAULT_CLIENT_INFO, FoldersTransport
60from .transports.grpc_asyncio import FoldersGrpcAsyncIOTransport
62try:
63 from google.api_core import client_logging # type: ignore
65 CLIENT_LOGGING_SUPPORTED = True # pragma: NO COVER
66except ImportError: # pragma: NO COVER
67 CLIENT_LOGGING_SUPPORTED = False
69_LOGGER = std_logging.getLogger(__name__)
72class FoldersAsyncClient:
73 """Manages Cloud Platform folder resources.
74 Folders can be used to organize the resources under an
75 organization and to control the policies applied to groups of
76 resources.
77 """
79 _client: FoldersClient
81 # Copy defaults from the synchronous client for use here.
82 # Note: DEFAULT_ENDPOINT is deprecated. Use _DEFAULT_ENDPOINT_TEMPLATE instead.
83 DEFAULT_ENDPOINT = FoldersClient.DEFAULT_ENDPOINT
84 DEFAULT_MTLS_ENDPOINT = FoldersClient.DEFAULT_MTLS_ENDPOINT
85 _DEFAULT_ENDPOINT_TEMPLATE = FoldersClient._DEFAULT_ENDPOINT_TEMPLATE
86 _DEFAULT_UNIVERSE = FoldersClient._DEFAULT_UNIVERSE
88 folder_path = staticmethod(FoldersClient.folder_path)
89 parse_folder_path = staticmethod(FoldersClient.parse_folder_path)
90 common_billing_account_path = staticmethod(
91 FoldersClient.common_billing_account_path
92 )
93 parse_common_billing_account_path = staticmethod(
94 FoldersClient.parse_common_billing_account_path
95 )
96 common_folder_path = staticmethod(FoldersClient.common_folder_path)
97 parse_common_folder_path = staticmethod(FoldersClient.parse_common_folder_path)
98 common_organization_path = staticmethod(FoldersClient.common_organization_path)
99 parse_common_organization_path = staticmethod(
100 FoldersClient.parse_common_organization_path
101 )
102 common_project_path = staticmethod(FoldersClient.common_project_path)
103 parse_common_project_path = staticmethod(FoldersClient.parse_common_project_path)
104 common_location_path = staticmethod(FoldersClient.common_location_path)
105 parse_common_location_path = staticmethod(FoldersClient.parse_common_location_path)
107 @classmethod
108 def from_service_account_info(cls, info: dict, *args, **kwargs):
109 """Creates an instance of this client using the provided credentials
110 info.
112 Args:
113 info (dict): The service account private key info.
114 args: Additional arguments to pass to the constructor.
115 kwargs: Additional arguments to pass to the constructor.
117 Returns:
118 FoldersAsyncClient: The constructed client.
119 """
120 return FoldersClient.from_service_account_info.__func__(FoldersAsyncClient, info, *args, **kwargs) # type: ignore
122 @classmethod
123 def from_service_account_file(cls, filename: str, *args, **kwargs):
124 """Creates an instance of this client using the provided credentials
125 file.
127 Args:
128 filename (str): The path to the service account private key json
129 file.
130 args: Additional arguments to pass to the constructor.
131 kwargs: Additional arguments to pass to the constructor.
133 Returns:
134 FoldersAsyncClient: The constructed client.
135 """
136 return FoldersClient.from_service_account_file.__func__(FoldersAsyncClient, filename, *args, **kwargs) # type: ignore
138 from_service_account_json = from_service_account_file
140 @classmethod
141 def get_mtls_endpoint_and_cert_source(
142 cls, client_options: Optional[ClientOptions] = None
143 ):
144 """Return the API endpoint and client cert source for mutual TLS.
146 The client cert source is determined in the following order:
147 (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
148 client cert source is None.
149 (2) if `client_options.client_cert_source` is provided, use the provided one; if the
150 default client cert source exists, use the default one; otherwise the client cert
151 source is None.
153 The API endpoint is determined in the following order:
154 (1) if `client_options.api_endpoint` if provided, use the provided one.
155 (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
156 default mTLS endpoint; if the environment variable is "never", use the default API
157 endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
158 use the default API endpoint.
160 More details can be found at https://google.aip.dev/auth/4114.
162 Args:
163 client_options (google.api_core.client_options.ClientOptions): Custom options for the
164 client. Only the `api_endpoint` and `client_cert_source` properties may be used
165 in this method.
167 Returns:
168 Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
169 client cert source to use.
171 Raises:
172 google.auth.exceptions.MutualTLSChannelError: If any errors happen.
173 """
174 return FoldersClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
176 @property
177 def transport(self) -> FoldersTransport:
178 """Returns the transport used by the client instance.
180 Returns:
181 FoldersTransport: The transport used by the client instance.
182 """
183 return self._client.transport
185 @property
186 def api_endpoint(self):
187 """Return the API endpoint used by the client instance.
189 Returns:
190 str: The API endpoint used by the client instance.
191 """
192 return self._client._api_endpoint
194 @property
195 def universe_domain(self) -> str:
196 """Return the universe domain used by the client instance.
198 Returns:
199 str: The universe domain used
200 by the client instance.
201 """
202 return self._client._universe_domain
204 get_transport_class = FoldersClient.get_transport_class
206 def __init__(
207 self,
208 *,
209 credentials: Optional[ga_credentials.Credentials] = None,
210 transport: Optional[
211 Union[str, FoldersTransport, Callable[..., FoldersTransport]]
212 ] = "grpc_asyncio",
213 client_options: Optional[ClientOptions] = None,
214 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
215 ) -> None:
216 """Instantiates the folders async client.
218 Args:
219 credentials (Optional[google.auth.credentials.Credentials]): The
220 authorization credentials to attach to requests. These
221 credentials identify the application to the service; if none
222 are specified, the client will attempt to ascertain the
223 credentials from the environment.
224 transport (Optional[Union[str,FoldersTransport,Callable[..., FoldersTransport]]]):
225 The transport to use, or a Callable that constructs and returns a new transport to use.
226 If a Callable is given, it will be called with the same set of initialization
227 arguments as used in the FoldersTransport constructor.
228 If set to None, a transport is chosen automatically.
229 client_options (Optional[Union[google.api_core.client_options.ClientOptions, dict]]):
230 Custom options for the client.
232 1. The ``api_endpoint`` property can be used to override the
233 default endpoint provided by the client when ``transport`` is
234 not explicitly provided. Only if this property is not set and
235 ``transport`` was not explicitly provided, the endpoint is
236 determined by the GOOGLE_API_USE_MTLS_ENDPOINT environment
237 variable, which have one of the following values:
238 "always" (always use the default mTLS endpoint), "never" (always
239 use the default regular endpoint) and "auto" (auto-switch to the
240 default mTLS endpoint if client certificate is present; this is
241 the default value).
243 2. If the GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
244 is "true", then the ``client_cert_source`` property can be used
245 to provide a client certificate for mTLS transport. If
246 not provided, the default SSL client certificate will be used if
247 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
248 set, no client certificate will be used.
250 3. The ``universe_domain`` property can be used to override the
251 default "googleapis.com" universe. Note that ``api_endpoint``
252 property still takes precedence; and ``universe_domain`` is
253 currently not supported for mTLS.
255 client_info (google.api_core.gapic_v1.client_info.ClientInfo):
256 The client info used to send a user-agent string along with
257 API requests. If ``None``, then default info will be used.
258 Generally, you only need to set this if you're developing
259 your own client library.
261 Raises:
262 google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
263 creation failed for any reason.
264 """
265 self._client = FoldersClient(
266 credentials=credentials,
267 transport=transport,
268 client_options=client_options,
269 client_info=client_info,
270 )
272 if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor(
273 std_logging.DEBUG
274 ): # pragma: NO COVER
275 _LOGGER.debug(
276 "Created client `google.cloud.resourcemanager_v3.FoldersAsyncClient`.",
277 extra={
278 "serviceName": "google.cloud.resourcemanager.v3.Folders",
279 "universeDomain": getattr(
280 self._client._transport._credentials, "universe_domain", ""
281 ),
282 "credentialsType": f"{type(self._client._transport._credentials).__module__}.{type(self._client._transport._credentials).__qualname__}",
283 "credentialsInfo": getattr(
284 self.transport._credentials, "get_cred_info", lambda: None
285 )(),
286 }
287 if hasattr(self._client._transport, "_credentials")
288 else {
289 "serviceName": "google.cloud.resourcemanager.v3.Folders",
290 "credentialsType": None,
291 },
292 )
294 async def get_folder(
295 self,
296 request: Optional[Union[folders.GetFolderRequest, dict]] = None,
297 *,
298 name: Optional[str] = None,
299 retry: OptionalRetry = gapic_v1.method.DEFAULT,
300 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
301 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
302 ) -> folders.Folder:
303 r"""Retrieves a folder identified by the supplied resource name.
304 Valid folder resource names have the format
305 ``folders/{folder_id}`` (for example, ``folders/1234``). The
306 caller must have ``resourcemanager.folders.get`` permission on
307 the identified folder.
309 .. code-block:: python
311 # This snippet has been automatically generated and should be regarded as a
312 # code template only.
313 # It will require modifications to work:
314 # - It may require correct/in-range values for request initialization.
315 # - It may require specifying regional endpoints when creating the service
316 # client as shown in:
317 # https://googleapis.dev/python/google-api-core/latest/client_options.html
318 from google.cloud import resourcemanager_v3
320 async def sample_get_folder():
321 # Create a client
322 client = resourcemanager_v3.FoldersAsyncClient()
324 # Initialize request argument(s)
325 request = resourcemanager_v3.GetFolderRequest(
326 name="name_value",
327 )
329 # Make the request
330 response = await client.get_folder(request=request)
332 # Handle the response
333 print(response)
335 Args:
336 request (Optional[Union[google.cloud.resourcemanager_v3.types.GetFolderRequest, dict]]):
337 The request object. The GetFolder request message.
338 name (:class:`str`):
339 Required. The resource name of the folder to retrieve.
340 Must be of the form ``folders/{folder_id}``.
342 This corresponds to the ``name`` field
343 on the ``request`` instance; if ``request`` is provided, this
344 should not be set.
345 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
346 should be retried.
347 timeout (float): The timeout for this request.
348 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
349 sent along with the request as metadata. Normally, each value must be of type `str`,
350 but for metadata keys ending with the suffix `-bin`, the corresponding values must
351 be of type `bytes`.
353 Returns:
354 google.cloud.resourcemanager_v3.types.Folder:
355 A folder in an organization's
356 resource hierarchy, used to organize
357 that organization's resources.
359 """
360 # Create or coerce a protobuf request object.
361 # - Quick check: If we got a request object, we should *not* have
362 # gotten any keyword arguments that map to the request.
363 flattened_params = [name]
364 has_flattened_params = (
365 len([param for param in flattened_params if param is not None]) > 0
366 )
367 if request is not None and has_flattened_params:
368 raise ValueError(
369 "If the `request` argument is set, then none of "
370 "the individual field arguments should be set."
371 )
373 # - Use the request object if provided (there's no risk of modifying the input as
374 # there are no flattened fields), or create one.
375 if not isinstance(request, folders.GetFolderRequest):
376 request = folders.GetFolderRequest(request)
378 # If we have keyword arguments corresponding to fields on the
379 # request, apply these.
380 if name is not None:
381 request.name = name
383 # Wrap the RPC method; this adds retry and timeout information,
384 # and friendly error handling.
385 rpc = self._client._transport._wrapped_methods[
386 self._client._transport.get_folder
387 ]
389 # Certain fields should be provided within the metadata header;
390 # add these here.
391 metadata = tuple(metadata) + (
392 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
393 )
395 # Validate the universe domain.
396 self._client._validate_universe_domain()
398 # Send the request.
399 response = await rpc(
400 request,
401 retry=retry,
402 timeout=timeout,
403 metadata=metadata,
404 )
406 # Done; return the response.
407 return response
409 async def list_folders(
410 self,
411 request: Optional[Union[folders.ListFoldersRequest, dict]] = None,
412 *,
413 parent: Optional[str] = None,
414 retry: OptionalRetry = gapic_v1.method.DEFAULT,
415 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
416 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
417 ) -> pagers.ListFoldersAsyncPager:
418 r"""Lists the folders that are direct descendants of supplied parent
419 resource. ``list()`` provides a strongly consistent view of the
420 folders underneath the specified parent resource. ``list()``
421 returns folders sorted based upon the (ascending) lexical
422 ordering of their display_name. The caller must have
423 ``resourcemanager.folders.list`` permission on the identified
424 parent.
426 .. code-block:: python
428 # This snippet has been automatically generated and should be regarded as a
429 # code template only.
430 # It will require modifications to work:
431 # - It may require correct/in-range values for request initialization.
432 # - It may require specifying regional endpoints when creating the service
433 # client as shown in:
434 # https://googleapis.dev/python/google-api-core/latest/client_options.html
435 from google.cloud import resourcemanager_v3
437 async def sample_list_folders():
438 # Create a client
439 client = resourcemanager_v3.FoldersAsyncClient()
441 # Initialize request argument(s)
442 request = resourcemanager_v3.ListFoldersRequest(
443 parent="parent_value",
444 )
446 # Make the request
447 page_result = client.list_folders(request=request)
449 # Handle the response
450 async for response in page_result:
451 print(response)
453 Args:
454 request (Optional[Union[google.cloud.resourcemanager_v3.types.ListFoldersRequest, dict]]):
455 The request object. The ListFolders request message.
456 parent (:class:`str`):
457 Required. The name of the parent resource whose folders
458 are being listed. Only children of this parent resource
459 are listed; descendants are not listed.
461 If the parent is a folder, use the value
462 ``folders/{folder_id}``. If the parent is an
463 organization, use the value ``organizations/{org_id}``.
465 Access to this method is controlled by checking the
466 ``resourcemanager.folders.list`` permission on the
467 ``parent``.
469 This corresponds to the ``parent`` field
470 on the ``request`` instance; if ``request`` is provided, this
471 should not be set.
472 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
473 should be retried.
474 timeout (float): The timeout for this request.
475 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
476 sent along with the request as metadata. Normally, each value must be of type `str`,
477 but for metadata keys ending with the suffix `-bin`, the corresponding values must
478 be of type `bytes`.
480 Returns:
481 google.cloud.resourcemanager_v3.services.folders.pagers.ListFoldersAsyncPager:
482 The ListFolders response message.
484 Iterating over this object will yield
485 results and resolve additional pages
486 automatically.
488 """
489 # Create or coerce a protobuf request object.
490 # - Quick check: If we got a request object, we should *not* have
491 # gotten any keyword arguments that map to the request.
492 flattened_params = [parent]
493 has_flattened_params = (
494 len([param for param in flattened_params if param is not None]) > 0
495 )
496 if request is not None and has_flattened_params:
497 raise ValueError(
498 "If the `request` argument is set, then none of "
499 "the individual field arguments should be set."
500 )
502 # - Use the request object if provided (there's no risk of modifying the input as
503 # there are no flattened fields), or create one.
504 if not isinstance(request, folders.ListFoldersRequest):
505 request = folders.ListFoldersRequest(request)
507 # If we have keyword arguments corresponding to fields on the
508 # request, apply these.
509 if parent is not None:
510 request.parent = parent
512 # Wrap the RPC method; this adds retry and timeout information,
513 # and friendly error handling.
514 rpc = self._client._transport._wrapped_methods[
515 self._client._transport.list_folders
516 ]
518 # Validate the universe domain.
519 self._client._validate_universe_domain()
521 # Send the request.
522 response = await rpc(
523 request,
524 retry=retry,
525 timeout=timeout,
526 metadata=metadata,
527 )
529 # This method is paged; wrap the response in a pager, which provides
530 # an `__aiter__` convenience method.
531 response = pagers.ListFoldersAsyncPager(
532 method=rpc,
533 request=request,
534 response=response,
535 retry=retry,
536 timeout=timeout,
537 metadata=metadata,
538 )
540 # Done; return the response.
541 return response
543 async def search_folders(
544 self,
545 request: Optional[Union[folders.SearchFoldersRequest, dict]] = None,
546 *,
547 query: Optional[str] = None,
548 retry: OptionalRetry = gapic_v1.method.DEFAULT,
549 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
550 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
551 ) -> pagers.SearchFoldersAsyncPager:
552 r"""Search for folders that match specific filter criteria.
553 ``search()`` provides an eventually consistent view of the
554 folders a user has access to which meet the specified filter
555 criteria.
557 This will only return folders on which the caller has the
558 permission ``resourcemanager.folders.get``.
560 .. code-block:: python
562 # This snippet has been automatically generated and should be regarded as a
563 # code template only.
564 # It will require modifications to work:
565 # - It may require correct/in-range values for request initialization.
566 # - It may require specifying regional endpoints when creating the service
567 # client as shown in:
568 # https://googleapis.dev/python/google-api-core/latest/client_options.html
569 from google.cloud import resourcemanager_v3
571 async def sample_search_folders():
572 # Create a client
573 client = resourcemanager_v3.FoldersAsyncClient()
575 # Initialize request argument(s)
576 request = resourcemanager_v3.SearchFoldersRequest(
577 )
579 # Make the request
580 page_result = client.search_folders(request=request)
582 # Handle the response
583 async for response in page_result:
584 print(response)
586 Args:
587 request (Optional[Union[google.cloud.resourcemanager_v3.types.SearchFoldersRequest, dict]]):
588 The request object. The request message for searching
589 folders.
590 query (:class:`str`):
591 Optional. Search criteria used to select the folders to
592 return. If no search criteria is specified then all
593 accessible folders will be returned.
595 Query expressions can be used to restrict results based
596 upon displayName, state and parent, where the operators
597 ``=`` (``:``) ``NOT``, ``AND`` and ``OR`` can be used
598 along with the suffix wildcard symbol ``*``.
600 The ``displayName`` field in a query expression should
601 use escaped quotes for values that include whitespace to
602 prevent unexpected behavior.
604 ::
606 | Field | Description |
607 |-------------------------|----------------------------------------|
608 | displayName | Filters by displayName. |
609 | parent | Filters by parent (for example: folders/123). |
610 | state, lifecycleState | Filters by state. |
612 Some example queries are:
614 - Query ``displayName=Test*`` returns Folder resources
615 whose display name starts with "Test".
616 - Query ``state=ACTIVE`` returns Folder resources with
617 ``state`` set to ``ACTIVE``.
618 - Query ``parent=folders/123`` returns Folder resources
619 that have ``folders/123`` as a parent resource.
620 - Query ``parent=folders/123 AND state=ACTIVE`` returns
621 active Folder resources that have ``folders/123`` as
622 a parent resource.
623 - Query ``displayName=\\"Test String\\"`` returns
624 Folder resources with display names that include both
625 "Test" and "String".
627 This corresponds to the ``query`` field
628 on the ``request`` instance; if ``request`` is provided, this
629 should not be set.
630 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
631 should be retried.
632 timeout (float): The timeout for this request.
633 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
634 sent along with the request as metadata. Normally, each value must be of type `str`,
635 but for metadata keys ending with the suffix `-bin`, the corresponding values must
636 be of type `bytes`.
638 Returns:
639 google.cloud.resourcemanager_v3.services.folders.pagers.SearchFoldersAsyncPager:
640 The response message for searching
641 folders.
642 Iterating over this object will yield
643 results and resolve additional pages
644 automatically.
646 """
647 # Create or coerce a protobuf request object.
648 # - Quick check: If we got a request object, we should *not* have
649 # gotten any keyword arguments that map to the request.
650 flattened_params = [query]
651 has_flattened_params = (
652 len([param for param in flattened_params if param is not None]) > 0
653 )
654 if request is not None and has_flattened_params:
655 raise ValueError(
656 "If the `request` argument is set, then none of "
657 "the individual field arguments should be set."
658 )
660 # - Use the request object if provided (there's no risk of modifying the input as
661 # there are no flattened fields), or create one.
662 if not isinstance(request, folders.SearchFoldersRequest):
663 request = folders.SearchFoldersRequest(request)
665 # If we have keyword arguments corresponding to fields on the
666 # request, apply these.
667 if query is not None:
668 request.query = query
670 # Wrap the RPC method; this adds retry and timeout information,
671 # and friendly error handling.
672 rpc = self._client._transport._wrapped_methods[
673 self._client._transport.search_folders
674 ]
676 # Validate the universe domain.
677 self._client._validate_universe_domain()
679 # Send the request.
680 response = await rpc(
681 request,
682 retry=retry,
683 timeout=timeout,
684 metadata=metadata,
685 )
687 # This method is paged; wrap the response in a pager, which provides
688 # an `__aiter__` convenience method.
689 response = pagers.SearchFoldersAsyncPager(
690 method=rpc,
691 request=request,
692 response=response,
693 retry=retry,
694 timeout=timeout,
695 metadata=metadata,
696 )
698 # Done; return the response.
699 return response
701 async def create_folder(
702 self,
703 request: Optional[Union[folders.CreateFolderRequest, dict]] = None,
704 *,
705 folder: Optional[folders.Folder] = None,
706 retry: OptionalRetry = gapic_v1.method.DEFAULT,
707 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
708 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
709 ) -> operation_async.AsyncOperation:
710 r"""Creates a folder in the resource hierarchy. Returns an
711 ``Operation`` which can be used to track the progress of the
712 folder creation workflow. Upon success, the
713 ``Operation.response`` field will be populated with the created
714 Folder.
716 In order to succeed, the addition of this new folder must not
717 violate the folder naming, height, or fanout constraints.
719 - The folder's ``display_name`` must be distinct from all other
720 folders that share its parent.
721 - The addition of the folder must not cause the active folder
722 hierarchy to exceed a height of 10. Note, the full active +
723 deleted folder hierarchy is allowed to reach a height of 20;
724 this provides additional headroom when moving folders that
725 contain deleted folders.
726 - The addition of the folder must not cause the total number of
727 folders under its parent to exceed 300.
729 If the operation fails due to a folder constraint violation,
730 some errors may be returned by the ``CreateFolder`` request,
731 with status code ``FAILED_PRECONDITION`` and an error
732 description. Other folder constraint violations will be
733 communicated in the ``Operation``, with the specific
734 ``PreconditionFailure`` returned in the details list in the
735 ``Operation.error`` field.
737 The caller must have ``resourcemanager.folders.create``
738 permission on the identified parent.
740 .. code-block:: python
742 # This snippet has been automatically generated and should be regarded as a
743 # code template only.
744 # It will require modifications to work:
745 # - It may require correct/in-range values for request initialization.
746 # - It may require specifying regional endpoints when creating the service
747 # client as shown in:
748 # https://googleapis.dev/python/google-api-core/latest/client_options.html
749 from google.cloud import resourcemanager_v3
751 async def sample_create_folder():
752 # Create a client
753 client = resourcemanager_v3.FoldersAsyncClient()
755 # Initialize request argument(s)
756 folder = resourcemanager_v3.Folder()
757 folder.parent = "parent_value"
759 request = resourcemanager_v3.CreateFolderRequest(
760 folder=folder,
761 )
763 # Make the request
764 operation = client.create_folder(request=request)
766 print("Waiting for operation to complete...")
768 response = (await operation).result()
770 # Handle the response
771 print(response)
773 Args:
774 request (Optional[Union[google.cloud.resourcemanager_v3.types.CreateFolderRequest, dict]]):
775 The request object. The CreateFolder request message.
776 folder (:class:`google.cloud.resourcemanager_v3.types.Folder`):
777 Required. The folder being created,
778 only the display name and parent will be
779 consulted. All other fields will be
780 ignored.
782 This corresponds to the ``folder`` field
783 on the ``request`` instance; if ``request`` is provided, this
784 should not be set.
785 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
786 should be retried.
787 timeout (float): The timeout for this request.
788 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
789 sent along with the request as metadata. Normally, each value must be of type `str`,
790 but for metadata keys ending with the suffix `-bin`, the corresponding values must
791 be of type `bytes`.
793 Returns:
794 google.api_core.operation_async.AsyncOperation:
795 An object representing a long-running operation.
797 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
798 organize that organization's resources.
800 """
801 # Create or coerce a protobuf request object.
802 # - Quick check: If we got a request object, we should *not* have
803 # gotten any keyword arguments that map to the request.
804 flattened_params = [folder]
805 has_flattened_params = (
806 len([param for param in flattened_params if param is not None]) > 0
807 )
808 if request is not None and has_flattened_params:
809 raise ValueError(
810 "If the `request` argument is set, then none of "
811 "the individual field arguments should be set."
812 )
814 # - Use the request object if provided (there's no risk of modifying the input as
815 # there are no flattened fields), or create one.
816 if not isinstance(request, folders.CreateFolderRequest):
817 request = folders.CreateFolderRequest(request)
819 # If we have keyword arguments corresponding to fields on the
820 # request, apply these.
821 if folder is not None:
822 request.folder = folder
824 # Wrap the RPC method; this adds retry and timeout information,
825 # and friendly error handling.
826 rpc = self._client._transport._wrapped_methods[
827 self._client._transport.create_folder
828 ]
830 # Validate the universe domain.
831 self._client._validate_universe_domain()
833 # Send the request.
834 response = await rpc(
835 request,
836 retry=retry,
837 timeout=timeout,
838 metadata=metadata,
839 )
841 # Wrap the response in an operation future.
842 response = operation_async.from_gapic(
843 response,
844 self._client._transport.operations_client,
845 folders.Folder,
846 metadata_type=folders.CreateFolderMetadata,
847 )
849 # Done; return the response.
850 return response
852 async def update_folder(
853 self,
854 request: Optional[Union[folders.UpdateFolderRequest, dict]] = None,
855 *,
856 folder: Optional[folders.Folder] = None,
857 update_mask: Optional[field_mask_pb2.FieldMask] = None,
858 retry: OptionalRetry = gapic_v1.method.DEFAULT,
859 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
860 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
861 ) -> operation_async.AsyncOperation:
862 r"""Updates a folder, changing its ``display_name``. Changes to the
863 folder ``display_name`` will be rejected if they violate either
864 the ``display_name`` formatting rules or the naming constraints
865 described in the
866 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
867 documentation.
869 The folder's ``display_name`` must start and end with a letter
870 or digit, may contain letters, digits, spaces, hyphens and
871 underscores and can be between 3 and 30 characters. This is
872 captured by the regular expression:
873 ``[\p{L}\p{N}][\p{L}\p{N}_- ]{1,28}[\p{L}\p{N}]``. The caller
874 must have ``resourcemanager.folders.update`` permission on the
875 identified folder.
877 If the update fails due to the unique name constraint then a
878 ``PreconditionFailure`` explaining this violation will be
879 returned in the Status.details field.
881 .. code-block:: python
883 # This snippet has been automatically generated and should be regarded as a
884 # code template only.
885 # It will require modifications to work:
886 # - It may require correct/in-range values for request initialization.
887 # - It may require specifying regional endpoints when creating the service
888 # client as shown in:
889 # https://googleapis.dev/python/google-api-core/latest/client_options.html
890 from google.cloud import resourcemanager_v3
892 async def sample_update_folder():
893 # Create a client
894 client = resourcemanager_v3.FoldersAsyncClient()
896 # Initialize request argument(s)
897 folder = resourcemanager_v3.Folder()
898 folder.parent = "parent_value"
900 request = resourcemanager_v3.UpdateFolderRequest(
901 folder=folder,
902 )
904 # Make the request
905 operation = client.update_folder(request=request)
907 print("Waiting for operation to complete...")
909 response = (await operation).result()
911 # Handle the response
912 print(response)
914 Args:
915 request (Optional[Union[google.cloud.resourcemanager_v3.types.UpdateFolderRequest, dict]]):
916 The request object. The request sent to the
917 [UpdateFolder][google.cloud.resourcemanager.v3.Folder.UpdateFolder]
918 method.
920 Only the ``display_name`` field can be changed. All
921 other fields will be ignored. Use the
922 [MoveFolder][google.cloud.resourcemanager.v3.Folders.MoveFolder]
923 method to change the ``parent`` field.
924 folder (:class:`google.cloud.resourcemanager_v3.types.Folder`):
925 Required. The new definition of the Folder. It must
926 include the ``name`` field, which cannot be changed.
928 This corresponds to the ``folder`` field
929 on the ``request`` instance; if ``request`` is provided, this
930 should not be set.
931 update_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`):
932 Required. Fields to be updated. Only the
933 ``display_name`` can be updated.
935 This corresponds to the ``update_mask`` field
936 on the ``request`` instance; if ``request`` is provided, this
937 should not be set.
938 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
939 should be retried.
940 timeout (float): The timeout for this request.
941 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
942 sent along with the request as metadata. Normally, each value must be of type `str`,
943 but for metadata keys ending with the suffix `-bin`, the corresponding values must
944 be of type `bytes`.
946 Returns:
947 google.api_core.operation_async.AsyncOperation:
948 An object representing a long-running operation.
950 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
951 organize that organization's resources.
953 """
954 # Create or coerce a protobuf request object.
955 # - Quick check: If we got a request object, we should *not* have
956 # gotten any keyword arguments that map to the request.
957 flattened_params = [folder, update_mask]
958 has_flattened_params = (
959 len([param for param in flattened_params if param is not None]) > 0
960 )
961 if request is not None and has_flattened_params:
962 raise ValueError(
963 "If the `request` argument is set, then none of "
964 "the individual field arguments should be set."
965 )
967 # - Use the request object if provided (there's no risk of modifying the input as
968 # there are no flattened fields), or create one.
969 if not isinstance(request, folders.UpdateFolderRequest):
970 request = folders.UpdateFolderRequest(request)
972 # If we have keyword arguments corresponding to fields on the
973 # request, apply these.
974 if folder is not None:
975 request.folder = folder
976 if update_mask is not None:
977 request.update_mask = update_mask
979 # Wrap the RPC method; this adds retry and timeout information,
980 # and friendly error handling.
981 rpc = self._client._transport._wrapped_methods[
982 self._client._transport.update_folder
983 ]
985 # Certain fields should be provided within the metadata header;
986 # add these here.
987 metadata = tuple(metadata) + (
988 gapic_v1.routing_header.to_grpc_metadata(
989 (("folder.name", request.folder.name),)
990 ),
991 )
993 # Validate the universe domain.
994 self._client._validate_universe_domain()
996 # Send the request.
997 response = await rpc(
998 request,
999 retry=retry,
1000 timeout=timeout,
1001 metadata=metadata,
1002 )
1004 # Wrap the response in an operation future.
1005 response = operation_async.from_gapic(
1006 response,
1007 self._client._transport.operations_client,
1008 folders.Folder,
1009 metadata_type=folders.UpdateFolderMetadata,
1010 )
1012 # Done; return the response.
1013 return response
1015 async def move_folder(
1016 self,
1017 request: Optional[Union[folders.MoveFolderRequest, dict]] = None,
1018 *,
1019 name: Optional[str] = None,
1020 destination_parent: Optional[str] = None,
1021 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1022 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1023 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1024 ) -> operation_async.AsyncOperation:
1025 r"""Moves a folder under a new resource parent. Returns an
1026 ``Operation`` which can be used to track the progress of the
1027 folder move workflow. Upon success, the ``Operation.response``
1028 field will be populated with the moved folder. Upon failure, a
1029 ``FolderOperationError`` categorizing the failure cause will be
1030 returned - if the failure occurs synchronously then the
1031 ``FolderOperationError`` will be returned in the
1032 ``Status.details`` field. If it occurs asynchronously, then the
1033 FolderOperation will be returned in the ``Operation.error``
1034 field. In addition, the ``Operation.metadata`` field will be
1035 populated with a ``FolderOperation`` message as an aid to
1036 stateless clients. Folder moves will be rejected if they violate
1037 either the naming, height, or fanout constraints described in
1038 the
1039 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
1040 documentation. The caller must have
1041 ``resourcemanager.folders.move`` permission on the folder's
1042 current and proposed new parent.
1044 .. code-block:: python
1046 # This snippet has been automatically generated and should be regarded as a
1047 # code template only.
1048 # It will require modifications to work:
1049 # - It may require correct/in-range values for request initialization.
1050 # - It may require specifying regional endpoints when creating the service
1051 # client as shown in:
1052 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1053 from google.cloud import resourcemanager_v3
1055 async def sample_move_folder():
1056 # Create a client
1057 client = resourcemanager_v3.FoldersAsyncClient()
1059 # Initialize request argument(s)
1060 request = resourcemanager_v3.MoveFolderRequest(
1061 name="name_value",
1062 destination_parent="destination_parent_value",
1063 )
1065 # Make the request
1066 operation = client.move_folder(request=request)
1068 print("Waiting for operation to complete...")
1070 response = (await operation).result()
1072 # Handle the response
1073 print(response)
1075 Args:
1076 request (Optional[Union[google.cloud.resourcemanager_v3.types.MoveFolderRequest, dict]]):
1077 The request object. The MoveFolder request message.
1078 name (:class:`str`):
1079 Required. The resource name of the Folder to move. Must
1080 be of the form folders/{folder_id}
1082 This corresponds to the ``name`` field
1083 on the ``request`` instance; if ``request`` is provided, this
1084 should not be set.
1085 destination_parent (:class:`str`):
1086 Required. The resource name of the folder or
1087 organization which should be the folder's new parent.
1088 Must be of the form ``folders/{folder_id}`` or
1089 ``organizations/{org_id}``.
1091 This corresponds to the ``destination_parent`` field
1092 on the ``request`` instance; if ``request`` is provided, this
1093 should not be set.
1094 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1095 should be retried.
1096 timeout (float): The timeout for this request.
1097 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1098 sent along with the request as metadata. Normally, each value must be of type `str`,
1099 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1100 be of type `bytes`.
1102 Returns:
1103 google.api_core.operation_async.AsyncOperation:
1104 An object representing a long-running operation.
1106 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
1107 organize that organization's resources.
1109 """
1110 # Create or coerce a protobuf request object.
1111 # - Quick check: If we got a request object, we should *not* have
1112 # gotten any keyword arguments that map to the request.
1113 flattened_params = [name, destination_parent]
1114 has_flattened_params = (
1115 len([param for param in flattened_params if param is not None]) > 0
1116 )
1117 if request is not None and has_flattened_params:
1118 raise ValueError(
1119 "If the `request` argument is set, then none of "
1120 "the individual field arguments should be set."
1121 )
1123 # - Use the request object if provided (there's no risk of modifying the input as
1124 # there are no flattened fields), or create one.
1125 if not isinstance(request, folders.MoveFolderRequest):
1126 request = folders.MoveFolderRequest(request)
1128 # If we have keyword arguments corresponding to fields on the
1129 # request, apply these.
1130 if name is not None:
1131 request.name = name
1132 if destination_parent is not None:
1133 request.destination_parent = destination_parent
1135 # Wrap the RPC method; this adds retry and timeout information,
1136 # and friendly error handling.
1137 rpc = self._client._transport._wrapped_methods[
1138 self._client._transport.move_folder
1139 ]
1141 # Certain fields should be provided within the metadata header;
1142 # add these here.
1143 metadata = tuple(metadata) + (
1144 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1145 )
1147 # Validate the universe domain.
1148 self._client._validate_universe_domain()
1150 # Send the request.
1151 response = await rpc(
1152 request,
1153 retry=retry,
1154 timeout=timeout,
1155 metadata=metadata,
1156 )
1158 # Wrap the response in an operation future.
1159 response = operation_async.from_gapic(
1160 response,
1161 self._client._transport.operations_client,
1162 folders.Folder,
1163 metadata_type=folders.MoveFolderMetadata,
1164 )
1166 # Done; return the response.
1167 return response
1169 async def delete_folder(
1170 self,
1171 request: Optional[Union[folders.DeleteFolderRequest, dict]] = None,
1172 *,
1173 name: Optional[str] = None,
1174 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1175 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1176 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1177 ) -> operation_async.AsyncOperation:
1178 r"""Requests deletion of a folder. The folder is moved into the
1179 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1180 state immediately, and is deleted approximately 30 days later.
1181 This method may only be called on an empty folder, where a
1182 folder is empty if it doesn't contain any folders or projects in
1183 the
1184 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1185 state. If called on a folder in
1186 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1187 state the operation will result in a no-op success. The caller
1188 must have ``resourcemanager.folders.delete`` permission on the
1189 identified folder.
1191 .. code-block:: python
1193 # This snippet has been automatically generated and should be regarded as a
1194 # code template only.
1195 # It will require modifications to work:
1196 # - It may require correct/in-range values for request initialization.
1197 # - It may require specifying regional endpoints when creating the service
1198 # client as shown in:
1199 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1200 from google.cloud import resourcemanager_v3
1202 async def sample_delete_folder():
1203 # Create a client
1204 client = resourcemanager_v3.FoldersAsyncClient()
1206 # Initialize request argument(s)
1207 request = resourcemanager_v3.DeleteFolderRequest(
1208 name="name_value",
1209 )
1211 # Make the request
1212 operation = client.delete_folder(request=request)
1214 print("Waiting for operation to complete...")
1216 response = (await operation).result()
1218 # Handle the response
1219 print(response)
1221 Args:
1222 request (Optional[Union[google.cloud.resourcemanager_v3.types.DeleteFolderRequest, dict]]):
1223 The request object. The DeleteFolder request message.
1224 name (:class:`str`):
1225 Required. The resource name of the folder to be deleted.
1226 Must be of the form ``folders/{folder_id}``.
1228 This corresponds to the ``name`` field
1229 on the ``request`` instance; if ``request`` is provided, this
1230 should not be set.
1231 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1232 should be retried.
1233 timeout (float): The timeout for this request.
1234 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1235 sent along with the request as metadata. Normally, each value must be of type `str`,
1236 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1237 be of type `bytes`.
1239 Returns:
1240 google.api_core.operation_async.AsyncOperation:
1241 An object representing a long-running operation.
1243 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
1244 organize that organization's resources.
1246 """
1247 # Create or coerce a protobuf request object.
1248 # - Quick check: If we got a request object, we should *not* have
1249 # gotten any keyword arguments that map to the request.
1250 flattened_params = [name]
1251 has_flattened_params = (
1252 len([param for param in flattened_params if param is not None]) > 0
1253 )
1254 if request is not None and has_flattened_params:
1255 raise ValueError(
1256 "If the `request` argument is set, then none of "
1257 "the individual field arguments should be set."
1258 )
1260 # - Use the request object if provided (there's no risk of modifying the input as
1261 # there are no flattened fields), or create one.
1262 if not isinstance(request, folders.DeleteFolderRequest):
1263 request = folders.DeleteFolderRequest(request)
1265 # If we have keyword arguments corresponding to fields on the
1266 # request, apply these.
1267 if name is not None:
1268 request.name = name
1270 # Wrap the RPC method; this adds retry and timeout information,
1271 # and friendly error handling.
1272 rpc = self._client._transport._wrapped_methods[
1273 self._client._transport.delete_folder
1274 ]
1276 # Certain fields should be provided within the metadata header;
1277 # add these here.
1278 metadata = tuple(metadata) + (
1279 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1280 )
1282 # Validate the universe domain.
1283 self._client._validate_universe_domain()
1285 # Send the request.
1286 response = await rpc(
1287 request,
1288 retry=retry,
1289 timeout=timeout,
1290 metadata=metadata,
1291 )
1293 # Wrap the response in an operation future.
1294 response = operation_async.from_gapic(
1295 response,
1296 self._client._transport.operations_client,
1297 folders.Folder,
1298 metadata_type=folders.DeleteFolderMetadata,
1299 )
1301 # Done; return the response.
1302 return response
1304 async def undelete_folder(
1305 self,
1306 request: Optional[Union[folders.UndeleteFolderRequest, dict]] = None,
1307 *,
1308 name: Optional[str] = None,
1309 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1310 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1311 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1312 ) -> operation_async.AsyncOperation:
1313 r"""Cancels the deletion request for a folder. This method may be
1314 called on a folder in any state. If the folder is in the
1315 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1316 state the result will be a no-op success. In order to succeed,
1317 the folder's parent must be in the
1318 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1319 state. In addition, reintroducing the folder into the tree must
1320 not violate folder naming, height, and fanout constraints
1321 described in the
1322 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
1323 documentation. The caller must have
1324 ``resourcemanager.folders.undelete`` permission on the
1325 identified folder.
1327 .. code-block:: python
1329 # This snippet has been automatically generated and should be regarded as a
1330 # code template only.
1331 # It will require modifications to work:
1332 # - It may require correct/in-range values for request initialization.
1333 # - It may require specifying regional endpoints when creating the service
1334 # client as shown in:
1335 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1336 from google.cloud import resourcemanager_v3
1338 async def sample_undelete_folder():
1339 # Create a client
1340 client = resourcemanager_v3.FoldersAsyncClient()
1342 # Initialize request argument(s)
1343 request = resourcemanager_v3.UndeleteFolderRequest(
1344 name="name_value",
1345 )
1347 # Make the request
1348 operation = client.undelete_folder(request=request)
1350 print("Waiting for operation to complete...")
1352 response = (await operation).result()
1354 # Handle the response
1355 print(response)
1357 Args:
1358 request (Optional[Union[google.cloud.resourcemanager_v3.types.UndeleteFolderRequest, dict]]):
1359 The request object. The UndeleteFolder request message.
1360 name (:class:`str`):
1361 Required. The resource name of the folder to undelete.
1362 Must be of the form ``folders/{folder_id}``.
1364 This corresponds to the ``name`` field
1365 on the ``request`` instance; if ``request`` is provided, this
1366 should not be set.
1367 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1368 should be retried.
1369 timeout (float): The timeout for this request.
1370 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1371 sent along with the request as metadata. Normally, each value must be of type `str`,
1372 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1373 be of type `bytes`.
1375 Returns:
1376 google.api_core.operation_async.AsyncOperation:
1377 An object representing a long-running operation.
1379 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
1380 organize that organization's resources.
1382 """
1383 # Create or coerce a protobuf request object.
1384 # - Quick check: If we got a request object, we should *not* have
1385 # gotten any keyword arguments that map to the request.
1386 flattened_params = [name]
1387 has_flattened_params = (
1388 len([param for param in flattened_params if param is not None]) > 0
1389 )
1390 if request is not None and has_flattened_params:
1391 raise ValueError(
1392 "If the `request` argument is set, then none of "
1393 "the individual field arguments should be set."
1394 )
1396 # - Use the request object if provided (there's no risk of modifying the input as
1397 # there are no flattened fields), or create one.
1398 if not isinstance(request, folders.UndeleteFolderRequest):
1399 request = folders.UndeleteFolderRequest(request)
1401 # If we have keyword arguments corresponding to fields on the
1402 # request, apply these.
1403 if name is not None:
1404 request.name = name
1406 # Wrap the RPC method; this adds retry and timeout information,
1407 # and friendly error handling.
1408 rpc = self._client._transport._wrapped_methods[
1409 self._client._transport.undelete_folder
1410 ]
1412 # Certain fields should be provided within the metadata header;
1413 # add these here.
1414 metadata = tuple(metadata) + (
1415 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1416 )
1418 # Validate the universe domain.
1419 self._client._validate_universe_domain()
1421 # Send the request.
1422 response = await rpc(
1423 request,
1424 retry=retry,
1425 timeout=timeout,
1426 metadata=metadata,
1427 )
1429 # Wrap the response in an operation future.
1430 response = operation_async.from_gapic(
1431 response,
1432 self._client._transport.operations_client,
1433 folders.Folder,
1434 metadata_type=folders.UndeleteFolderMetadata,
1435 )
1437 # Done; return the response.
1438 return response
1440 async def get_iam_policy(
1441 self,
1442 request: Optional[Union[iam_policy_pb2.GetIamPolicyRequest, dict]] = None,
1443 *,
1444 resource: Optional[str] = None,
1445 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1446 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1447 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1448 ) -> policy_pb2.Policy:
1449 r"""Gets the access control policy for a folder. The returned policy
1450 may be empty if no such policy or resource exists. The
1451 ``resource`` field should be the folder's resource name, for
1452 example: "folders/1234". The caller must have
1453 ``resourcemanager.folders.getIamPolicy`` permission on the
1454 identified folder.
1456 .. code-block:: python
1458 # This snippet has been automatically generated and should be regarded as a
1459 # code template only.
1460 # It will require modifications to work:
1461 # - It may require correct/in-range values for request initialization.
1462 # - It may require specifying regional endpoints when creating the service
1463 # client as shown in:
1464 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1465 from google.cloud import resourcemanager_v3
1466 from google.iam.v1 import iam_policy_pb2 # type: ignore
1468 async def sample_get_iam_policy():
1469 # Create a client
1470 client = resourcemanager_v3.FoldersAsyncClient()
1472 # Initialize request argument(s)
1473 request = iam_policy_pb2.GetIamPolicyRequest(
1474 resource="resource_value",
1475 )
1477 # Make the request
1478 response = await client.get_iam_policy(request=request)
1480 # Handle the response
1481 print(response)
1483 Args:
1484 request (Optional[Union[google.iam.v1.iam_policy_pb2.GetIamPolicyRequest, dict]]):
1485 The request object. Request message for ``GetIamPolicy`` method.
1486 resource (:class:`str`):
1487 REQUIRED: The resource for which the
1488 policy is being requested. See the
1489 operation documentation for the
1490 appropriate value for this field.
1492 This corresponds to the ``resource`` field
1493 on the ``request`` instance; if ``request`` is provided, this
1494 should not be set.
1495 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1496 should be retried.
1497 timeout (float): The timeout for this request.
1498 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1499 sent along with the request as metadata. Normally, each value must be of type `str`,
1500 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1501 be of type `bytes`.
1503 Returns:
1504 google.iam.v1.policy_pb2.Policy:
1505 An Identity and Access Management (IAM) policy, which specifies access
1506 controls for Google Cloud resources.
1508 A Policy is a collection of bindings. A binding binds
1509 one or more members, or principals, to a single role.
1510 Principals can be user accounts, service accounts,
1511 Google groups, and domains (such as G Suite). A role
1512 is a named list of permissions; each role can be an
1513 IAM predefined role or a user-created custom role.
1515 For some types of Google Cloud resources, a binding
1516 can also specify a condition, which is a logical
1517 expression that allows access to a resource only if
1518 the expression evaluates to true. A condition can add
1519 constraints based on attributes of the request, the
1520 resource, or both. To learn which resources support
1521 conditions in their IAM policies, see the [IAM
1522 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1524 **JSON example:**
1526 :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \`
1528 **YAML example:**
1530 :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \`
1532 For a description of IAM and its features, see the
1533 [IAM
1534 documentation](\ https://cloud.google.com/iam/docs/).
1536 """
1537 # Create or coerce a protobuf request object.
1538 # - Quick check: If we got a request object, we should *not* have
1539 # gotten any keyword arguments that map to the request.
1540 flattened_params = [resource]
1541 has_flattened_params = (
1542 len([param for param in flattened_params if param is not None]) > 0
1543 )
1544 if request is not None and has_flattened_params:
1545 raise ValueError(
1546 "If the `request` argument is set, then none of "
1547 "the individual field arguments should be set."
1548 )
1550 # - The request isn't a proto-plus wrapped type,
1551 # so it must be constructed via keyword expansion.
1552 if isinstance(request, dict):
1553 request = iam_policy_pb2.GetIamPolicyRequest(**request)
1554 elif not request:
1555 request = iam_policy_pb2.GetIamPolicyRequest(resource=resource)
1557 # Wrap the RPC method; this adds retry and timeout information,
1558 # and friendly error handling.
1559 rpc = self._client._transport._wrapped_methods[
1560 self._client._transport.get_iam_policy
1561 ]
1563 # Certain fields should be provided within the metadata header;
1564 # add these here.
1565 metadata = tuple(metadata) + (
1566 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1567 )
1569 # Validate the universe domain.
1570 self._client._validate_universe_domain()
1572 # Send the request.
1573 response = await rpc(
1574 request,
1575 retry=retry,
1576 timeout=timeout,
1577 metadata=metadata,
1578 )
1580 # Done; return the response.
1581 return response
1583 async def set_iam_policy(
1584 self,
1585 request: Optional[Union[iam_policy_pb2.SetIamPolicyRequest, dict]] = None,
1586 *,
1587 resource: Optional[str] = None,
1588 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1589 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1590 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1591 ) -> policy_pb2.Policy:
1592 r"""Sets the access control policy on a folder, replacing any
1593 existing policy. The ``resource`` field should be the folder's
1594 resource name, for example: "folders/1234". The caller must have
1595 ``resourcemanager.folders.setIamPolicy`` permission on the
1596 identified folder.
1598 .. code-block:: python
1600 # This snippet has been automatically generated and should be regarded as a
1601 # code template only.
1602 # It will require modifications to work:
1603 # - It may require correct/in-range values for request initialization.
1604 # - It may require specifying regional endpoints when creating the service
1605 # client as shown in:
1606 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1607 from google.cloud import resourcemanager_v3
1608 from google.iam.v1 import iam_policy_pb2 # type: ignore
1610 async def sample_set_iam_policy():
1611 # Create a client
1612 client = resourcemanager_v3.FoldersAsyncClient()
1614 # Initialize request argument(s)
1615 request = iam_policy_pb2.SetIamPolicyRequest(
1616 resource="resource_value",
1617 )
1619 # Make the request
1620 response = await client.set_iam_policy(request=request)
1622 # Handle the response
1623 print(response)
1625 Args:
1626 request (Optional[Union[google.iam.v1.iam_policy_pb2.SetIamPolicyRequest, dict]]):
1627 The request object. Request message for ``SetIamPolicy`` method.
1628 resource (:class:`str`):
1629 REQUIRED: The resource for which the
1630 policy is being specified. See the
1631 operation documentation for the
1632 appropriate value for this field.
1634 This corresponds to the ``resource`` field
1635 on the ``request`` instance; if ``request`` is provided, this
1636 should not be set.
1637 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1638 should be retried.
1639 timeout (float): The timeout for this request.
1640 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1641 sent along with the request as metadata. Normally, each value must be of type `str`,
1642 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1643 be of type `bytes`.
1645 Returns:
1646 google.iam.v1.policy_pb2.Policy:
1647 An Identity and Access Management (IAM) policy, which specifies access
1648 controls for Google Cloud resources.
1650 A Policy is a collection of bindings. A binding binds
1651 one or more members, or principals, to a single role.
1652 Principals can be user accounts, service accounts,
1653 Google groups, and domains (such as G Suite). A role
1654 is a named list of permissions; each role can be an
1655 IAM predefined role or a user-created custom role.
1657 For some types of Google Cloud resources, a binding
1658 can also specify a condition, which is a logical
1659 expression that allows access to a resource only if
1660 the expression evaluates to true. A condition can add
1661 constraints based on attributes of the request, the
1662 resource, or both. To learn which resources support
1663 conditions in their IAM policies, see the [IAM
1664 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1666 **JSON example:**
1668 :literal:`\` { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members": [ "user:mike@example.com", "group:admins@example.com", "domain:google.com", "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role": "roles/resourcemanager.organizationViewer", "members": [ "user:eve@example.com" ], "condition": { "title": "expirable access", "description": "Does not grant access after Sep 2020", "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')", } } ], "etag": "BwWWja0YfJA=", "version": 3 }`\ \`
1670 **YAML example:**
1672 :literal:`\` bindings: - members: - user:mike@example.com - group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com role: roles/resourcemanager.organizationViewer condition: title: expirable access description: Does not grant access after Sep 2020 expression: request.time < timestamp('2020-10-01T00:00:00.000Z') etag: BwWWja0YfJA= version: 3`\ \`
1674 For a description of IAM and its features, see the
1675 [IAM
1676 documentation](\ https://cloud.google.com/iam/docs/).
1678 """
1679 # Create or coerce a protobuf request object.
1680 # - Quick check: If we got a request object, we should *not* have
1681 # gotten any keyword arguments that map to the request.
1682 flattened_params = [resource]
1683 has_flattened_params = (
1684 len([param for param in flattened_params if param is not None]) > 0
1685 )
1686 if request is not None and has_flattened_params:
1687 raise ValueError(
1688 "If the `request` argument is set, then none of "
1689 "the individual field arguments should be set."
1690 )
1692 # - The request isn't a proto-plus wrapped type,
1693 # so it must be constructed via keyword expansion.
1694 if isinstance(request, dict):
1695 request = iam_policy_pb2.SetIamPolicyRequest(**request)
1696 elif not request:
1697 request = iam_policy_pb2.SetIamPolicyRequest(resource=resource)
1699 # Wrap the RPC method; this adds retry and timeout information,
1700 # and friendly error handling.
1701 rpc = self._client._transport._wrapped_methods[
1702 self._client._transport.set_iam_policy
1703 ]
1705 # Certain fields should be provided within the metadata header;
1706 # add these here.
1707 metadata = tuple(metadata) + (
1708 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1709 )
1711 # Validate the universe domain.
1712 self._client._validate_universe_domain()
1714 # Send the request.
1715 response = await rpc(
1716 request,
1717 retry=retry,
1718 timeout=timeout,
1719 metadata=metadata,
1720 )
1722 # Done; return the response.
1723 return response
1725 async def test_iam_permissions(
1726 self,
1727 request: Optional[Union[iam_policy_pb2.TestIamPermissionsRequest, dict]] = None,
1728 *,
1729 resource: Optional[str] = None,
1730 permissions: Optional[MutableSequence[str]] = None,
1731 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1732 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1733 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1734 ) -> iam_policy_pb2.TestIamPermissionsResponse:
1735 r"""Returns permissions that a caller has on the specified folder.
1736 The ``resource`` field should be the folder's resource name, for
1737 example: "folders/1234".
1739 There are no permissions required for making this API call.
1741 .. code-block:: python
1743 # This snippet has been automatically generated and should be regarded as a
1744 # code template only.
1745 # It will require modifications to work:
1746 # - It may require correct/in-range values for request initialization.
1747 # - It may require specifying regional endpoints when creating the service
1748 # client as shown in:
1749 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1750 from google.cloud import resourcemanager_v3
1751 from google.iam.v1 import iam_policy_pb2 # type: ignore
1753 async def sample_test_iam_permissions():
1754 # Create a client
1755 client = resourcemanager_v3.FoldersAsyncClient()
1757 # Initialize request argument(s)
1758 request = iam_policy_pb2.TestIamPermissionsRequest(
1759 resource="resource_value",
1760 permissions=['permissions_value1', 'permissions_value2'],
1761 )
1763 # Make the request
1764 response = await client.test_iam_permissions(request=request)
1766 # Handle the response
1767 print(response)
1769 Args:
1770 request (Optional[Union[google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest, dict]]):
1771 The request object. Request message for ``TestIamPermissions`` method.
1772 resource (:class:`str`):
1773 REQUIRED: The resource for which the
1774 policy detail is being requested. See
1775 the operation documentation for the
1776 appropriate value for this field.
1778 This corresponds to the ``resource`` field
1779 on the ``request`` instance; if ``request`` is provided, this
1780 should not be set.
1781 permissions (:class:`MutableSequence[str]`):
1782 The set of permissions to check for the ``resource``.
1783 Permissions with wildcards (such as '*' or 'storage.*')
1784 are not allowed. For more information see `IAM
1785 Overview <https://cloud.google.com/iam/docs/overview#permissions>`__.
1787 This corresponds to the ``permissions`` field
1788 on the ``request`` instance; if ``request`` is provided, this
1789 should not be set.
1790 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,
1791 should be retried.
1792 timeout (float): The timeout for this request.
1793 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1794 sent along with the request as metadata. Normally, each value must be of type `str`,
1795 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1796 be of type `bytes`.
1798 Returns:
1799 google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse:
1800 Response message for TestIamPermissions method.
1801 """
1802 # Create or coerce a protobuf request object.
1803 # - Quick check: If we got a request object, we should *not* have
1804 # gotten any keyword arguments that map to the request.
1805 flattened_params = [resource, permissions]
1806 has_flattened_params = (
1807 len([param for param in flattened_params if param is not None]) > 0
1808 )
1809 if request is not None and has_flattened_params:
1810 raise ValueError(
1811 "If the `request` argument is set, then none of "
1812 "the individual field arguments should be set."
1813 )
1815 # - The request isn't a proto-plus wrapped type,
1816 # so it must be constructed via keyword expansion.
1817 if isinstance(request, dict):
1818 request = iam_policy_pb2.TestIamPermissionsRequest(**request)
1819 elif not request:
1820 request = iam_policy_pb2.TestIamPermissionsRequest(
1821 resource=resource, permissions=permissions
1822 )
1824 # Wrap the RPC method; this adds retry and timeout information,
1825 # and friendly error handling.
1826 rpc = self._client._transport._wrapped_methods[
1827 self._client._transport.test_iam_permissions
1828 ]
1830 # Certain fields should be provided within the metadata header;
1831 # add these here.
1832 metadata = tuple(metadata) + (
1833 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1834 )
1836 # Validate the universe domain.
1837 self._client._validate_universe_domain()
1839 # Send the request.
1840 response = await rpc(
1841 request,
1842 retry=retry,
1843 timeout=timeout,
1844 metadata=metadata,
1845 )
1847 # Done; return the response.
1848 return response
1850 async def get_operation(
1851 self,
1852 request: Optional[operations_pb2.GetOperationRequest] = None,
1853 *,
1854 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1855 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1856 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
1857 ) -> operations_pb2.Operation:
1858 r"""Gets the latest state of a long-running operation.
1860 Args:
1861 request (:class:`~.operations_pb2.GetOperationRequest`):
1862 The request object. Request message for
1863 `GetOperation` method.
1864 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors,
1865 if any, should be retried.
1866 timeout (float): The timeout for this request.
1867 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be
1868 sent along with the request as metadata. Normally, each value must be of type `str`,
1869 but for metadata keys ending with the suffix `-bin`, the corresponding values must
1870 be of type `bytes`.
1871 Returns:
1872 ~.operations_pb2.Operation:
1873 An ``Operation`` object.
1874 """
1875 # Create or coerce a protobuf request object.
1876 # The request isn't a proto-plus wrapped type,
1877 # so it must be constructed via keyword expansion.
1878 if isinstance(request, dict):
1879 request = operations_pb2.GetOperationRequest(**request)
1881 # Wrap the RPC method; this adds retry and timeout information,
1882 # and friendly error handling.
1883 rpc = self.transport._wrapped_methods[self._client._transport.get_operation]
1885 # Certain fields should be provided within the metadata header;
1886 # add these here.
1887 metadata = tuple(metadata) + (
1888 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1889 )
1891 # Validate the universe domain.
1892 self._client._validate_universe_domain()
1894 # Send the request.
1895 response = await rpc(
1896 request,
1897 retry=retry,
1898 timeout=timeout,
1899 metadata=metadata,
1900 )
1902 # Done; return the response.
1903 return response
1905 async def __aenter__(self) -> "FoldersAsyncClient":
1906 return self
1908 async def __aexit__(self, exc_type, exc, tb):
1909 await self.transport.close()
1912DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
1913 gapic_version=package_version.__version__
1914)
1916if hasattr(DEFAULT_CLIENT_INFO, "protobuf_runtime_version"): # pragma: NO COVER
1917 DEFAULT_CLIENT_INFO.protobuf_runtime_version = google.protobuf.__version__
1920__all__ = ("FoldersAsyncClient",)