Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/resourcemanager_v3/services/folders/client.py: 31%
313 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 os
18import re
19from typing import (
20 Dict,
21 Mapping,
22 MutableMapping,
23 MutableSequence,
24 Optional,
25 Sequence,
26 Tuple,
27 Type,
28 Union,
29 cast,
30)
32from google.api_core import client_options as client_options_lib
33from google.api_core import exceptions as core_exceptions
34from google.api_core import gapic_v1
35from google.api_core import retry as retries
36from google.auth import credentials as ga_credentials # type: ignore
37from google.auth.exceptions import MutualTLSChannelError # type: ignore
38from google.auth.transport import mtls # type: ignore
39from google.auth.transport.grpc import SslCredentials # type: ignore
40from google.oauth2 import service_account # type: ignore
42from google.cloud.resourcemanager_v3 import gapic_version as package_version
44try:
45 OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
46except AttributeError: # pragma: NO COVER
47 OptionalRetry = Union[retries.Retry, object] # type: ignore
49from google.api_core import operation # type: ignore
50from google.api_core import operation_async # type: ignore
51from google.iam.v1 import iam_policy_pb2 # type: ignore
52from google.iam.v1 import policy_pb2 # type: ignore
53from google.longrunning import operations_pb2
54from google.protobuf import field_mask_pb2 # type: ignore
55from google.protobuf import timestamp_pb2 # type: ignore
57from google.cloud.resourcemanager_v3.services.folders import pagers
58from google.cloud.resourcemanager_v3.types import folders
60from .transports.base import DEFAULT_CLIENT_INFO, FoldersTransport
61from .transports.grpc import FoldersGrpcTransport
62from .transports.grpc_asyncio import FoldersGrpcAsyncIOTransport
63from .transports.rest import FoldersRestTransport
66class FoldersClientMeta(type):
67 """Metaclass for the Folders client.
69 This provides class-level methods for building and retrieving
70 support objects (e.g. transport) without polluting the client instance
71 objects.
72 """
74 _transport_registry = OrderedDict() # type: Dict[str, Type[FoldersTransport]]
75 _transport_registry["grpc"] = FoldersGrpcTransport
76 _transport_registry["grpc_asyncio"] = FoldersGrpcAsyncIOTransport
77 _transport_registry["rest"] = FoldersRestTransport
79 def get_transport_class(
80 cls,
81 label: Optional[str] = None,
82 ) -> Type[FoldersTransport]:
83 """Returns an appropriate transport class.
85 Args:
86 label: The name of the desired transport. If none is
87 provided, then the first transport in the registry is used.
89 Returns:
90 The transport class to use.
91 """
92 # If a specific transport is requested, return that one.
93 if label:
94 return cls._transport_registry[label]
96 # No transport is requested; return the default (that is, the first one
97 # in the dictionary).
98 return next(iter(cls._transport_registry.values()))
101class FoldersClient(metaclass=FoldersClientMeta):
102 """Manages Cloud Platform folder resources.
103 Folders can be used to organize the resources under an
104 organization and to control the policies applied to groups of
105 resources.
106 """
108 @staticmethod
109 def _get_default_mtls_endpoint(api_endpoint):
110 """Converts api endpoint to mTLS endpoint.
112 Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
113 "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
114 Args:
115 api_endpoint (Optional[str]): the api endpoint to convert.
116 Returns:
117 str: converted mTLS api endpoint.
118 """
119 if not api_endpoint:
120 return api_endpoint
122 mtls_endpoint_re = re.compile(
123 r"(?P<name>[^.]+)(?P<mtls>\.mtls)?(?P<sandbox>\.sandbox)?(?P<googledomain>\.googleapis\.com)?"
124 )
126 m = mtls_endpoint_re.match(api_endpoint)
127 name, mtls, sandbox, googledomain = m.groups()
128 if mtls or not googledomain:
129 return api_endpoint
131 if sandbox:
132 return api_endpoint.replace(
133 "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
134 )
136 return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
138 DEFAULT_ENDPOINT = "cloudresourcemanager.googleapis.com"
139 DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
140 DEFAULT_ENDPOINT
141 )
143 @classmethod
144 def from_service_account_info(cls, info: dict, *args, **kwargs):
145 """Creates an instance of this client using the provided credentials
146 info.
148 Args:
149 info (dict): The service account private key info.
150 args: Additional arguments to pass to the constructor.
151 kwargs: Additional arguments to pass to the constructor.
153 Returns:
154 FoldersClient: The constructed client.
155 """
156 credentials = service_account.Credentials.from_service_account_info(info)
157 kwargs["credentials"] = credentials
158 return cls(*args, **kwargs)
160 @classmethod
161 def from_service_account_file(cls, filename: str, *args, **kwargs):
162 """Creates an instance of this client using the provided credentials
163 file.
165 Args:
166 filename (str): The path to the service account private key json
167 file.
168 args: Additional arguments to pass to the constructor.
169 kwargs: Additional arguments to pass to the constructor.
171 Returns:
172 FoldersClient: The constructed client.
173 """
174 credentials = service_account.Credentials.from_service_account_file(filename)
175 kwargs["credentials"] = credentials
176 return cls(*args, **kwargs)
178 from_service_account_json = from_service_account_file
180 @property
181 def transport(self) -> FoldersTransport:
182 """Returns the transport used by the client instance.
184 Returns:
185 FoldersTransport: The transport used by the client
186 instance.
187 """
188 return self._transport
190 @staticmethod
191 def folder_path(
192 folder: str,
193 ) -> str:
194 """Returns a fully-qualified folder string."""
195 return "folders/{folder}".format(
196 folder=folder,
197 )
199 @staticmethod
200 def parse_folder_path(path: str) -> Dict[str, str]:
201 """Parses a folder path into its component segments."""
202 m = re.match(r"^folders/(?P<folder>.+?)$", path)
203 return m.groupdict() if m else {}
205 @staticmethod
206 def common_billing_account_path(
207 billing_account: str,
208 ) -> str:
209 """Returns a fully-qualified billing_account string."""
210 return "billingAccounts/{billing_account}".format(
211 billing_account=billing_account,
212 )
214 @staticmethod
215 def parse_common_billing_account_path(path: str) -> Dict[str, str]:
216 """Parse a billing_account path into its component segments."""
217 m = re.match(r"^billingAccounts/(?P<billing_account>.+?)$", path)
218 return m.groupdict() if m else {}
220 @staticmethod
221 def common_folder_path(
222 folder: str,
223 ) -> str:
224 """Returns a fully-qualified folder string."""
225 return "folders/{folder}".format(
226 folder=folder,
227 )
229 @staticmethod
230 def parse_common_folder_path(path: str) -> Dict[str, str]:
231 """Parse a folder path into its component segments."""
232 m = re.match(r"^folders/(?P<folder>.+?)$", path)
233 return m.groupdict() if m else {}
235 @staticmethod
236 def common_organization_path(
237 organization: str,
238 ) -> str:
239 """Returns a fully-qualified organization string."""
240 return "organizations/{organization}".format(
241 organization=organization,
242 )
244 @staticmethod
245 def parse_common_organization_path(path: str) -> Dict[str, str]:
246 """Parse a organization path into its component segments."""
247 m = re.match(r"^organizations/(?P<organization>.+?)$", path)
248 return m.groupdict() if m else {}
250 @staticmethod
251 def common_project_path(
252 project: str,
253 ) -> str:
254 """Returns a fully-qualified project string."""
255 return "projects/{project}".format(
256 project=project,
257 )
259 @staticmethod
260 def parse_common_project_path(path: str) -> Dict[str, str]:
261 """Parse a project path into its component segments."""
262 m = re.match(r"^projects/(?P<project>.+?)$", path)
263 return m.groupdict() if m else {}
265 @staticmethod
266 def common_location_path(
267 project: str,
268 location: str,
269 ) -> str:
270 """Returns a fully-qualified location string."""
271 return "projects/{project}/locations/{location}".format(
272 project=project,
273 location=location,
274 )
276 @staticmethod
277 def parse_common_location_path(path: str) -> Dict[str, str]:
278 """Parse a location path into its component segments."""
279 m = re.match(r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)$", path)
280 return m.groupdict() if m else {}
282 @classmethod
283 def get_mtls_endpoint_and_cert_source(
284 cls, client_options: Optional[client_options_lib.ClientOptions] = None
285 ):
286 """Return the API endpoint and client cert source for mutual TLS.
288 The client cert source is determined in the following order:
289 (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
290 client cert source is None.
291 (2) if `client_options.client_cert_source` is provided, use the provided one; if the
292 default client cert source exists, use the default one; otherwise the client cert
293 source is None.
295 The API endpoint is determined in the following order:
296 (1) if `client_options.api_endpoint` if provided, use the provided one.
297 (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
298 default mTLS endpoint; if the environment variable is "never", use the default API
299 endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
300 use the default API endpoint.
302 More details can be found at https://google.aip.dev/auth/4114.
304 Args:
305 client_options (google.api_core.client_options.ClientOptions): Custom options for the
306 client. Only the `api_endpoint` and `client_cert_source` properties may be used
307 in this method.
309 Returns:
310 Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
311 client cert source to use.
313 Raises:
314 google.auth.exceptions.MutualTLSChannelError: If any errors happen.
315 """
316 if client_options is None:
317 client_options = client_options_lib.ClientOptions()
318 use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
319 use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
320 if use_client_cert not in ("true", "false"):
321 raise ValueError(
322 "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
323 )
324 if use_mtls_endpoint not in ("auto", "never", "always"):
325 raise MutualTLSChannelError(
326 "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
327 )
329 # Figure out the client cert source to use.
330 client_cert_source = None
331 if use_client_cert == "true":
332 if client_options.client_cert_source:
333 client_cert_source = client_options.client_cert_source
334 elif mtls.has_default_client_cert_source():
335 client_cert_source = mtls.default_client_cert_source()
337 # Figure out which api endpoint to use.
338 if client_options.api_endpoint is not None:
339 api_endpoint = client_options.api_endpoint
340 elif use_mtls_endpoint == "always" or (
341 use_mtls_endpoint == "auto" and client_cert_source
342 ):
343 api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
344 else:
345 api_endpoint = cls.DEFAULT_ENDPOINT
347 return api_endpoint, client_cert_source
349 def __init__(
350 self,
351 *,
352 credentials: Optional[ga_credentials.Credentials] = None,
353 transport: Optional[Union[str, FoldersTransport]] = None,
354 client_options: Optional[Union[client_options_lib.ClientOptions, dict]] = None,
355 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
356 ) -> None:
357 """Instantiates the folders client.
359 Args:
360 credentials (Optional[google.auth.credentials.Credentials]): The
361 authorization credentials to attach to requests. These
362 credentials identify the application to the service; if none
363 are specified, the client will attempt to ascertain the
364 credentials from the environment.
365 transport (Union[str, FoldersTransport]): The
366 transport to use. If set to None, a transport is chosen
367 automatically.
368 client_options (Optional[Union[google.api_core.client_options.ClientOptions, dict]]): Custom options for the
369 client. It won't take effect if a ``transport`` instance is provided.
370 (1) The ``api_endpoint`` property can be used to override the
371 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
372 environment variable can also be used to override the endpoint:
373 "always" (always use the default mTLS endpoint), "never" (always
374 use the default regular endpoint) and "auto" (auto switch to the
375 default mTLS endpoint if client certificate is present, this is
376 the default value). However, the ``api_endpoint`` property takes
377 precedence if provided.
378 (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
379 is "true", then the ``client_cert_source`` property can be used
380 to provide client certificate for mutual TLS transport. If
381 not provided, the default SSL client certificate will be used if
382 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
383 set, no client certificate will be used.
384 client_info (google.api_core.gapic_v1.client_info.ClientInfo):
385 The client info used to send a user-agent string along with
386 API requests. If ``None``, then default info will be used.
387 Generally, you only need to set this if you're developing
388 your own client library.
390 Raises:
391 google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
392 creation failed for any reason.
393 """
394 if isinstance(client_options, dict):
395 client_options = client_options_lib.from_dict(client_options)
396 if client_options is None:
397 client_options = client_options_lib.ClientOptions()
398 client_options = cast(client_options_lib.ClientOptions, client_options)
400 api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
401 client_options
402 )
404 api_key_value = getattr(client_options, "api_key", None)
405 if api_key_value and credentials:
406 raise ValueError(
407 "client_options.api_key and credentials are mutually exclusive"
408 )
410 # Save or instantiate the transport.
411 # Ordinarily, we provide the transport, but allowing a custom transport
412 # instance provides an extensibility point for unusual situations.
413 if isinstance(transport, FoldersTransport):
414 # transport is a FoldersTransport instance.
415 if credentials or client_options.credentials_file or api_key_value:
416 raise ValueError(
417 "When providing a transport instance, "
418 "provide its credentials directly."
419 )
420 if client_options.scopes:
421 raise ValueError(
422 "When providing a transport instance, provide its scopes "
423 "directly."
424 )
425 self._transport = transport
426 else:
427 import google.auth._default # type: ignore
429 if api_key_value and hasattr(
430 google.auth._default, "get_api_key_credentials"
431 ):
432 credentials = google.auth._default.get_api_key_credentials(
433 api_key_value
434 )
436 Transport = type(self).get_transport_class(transport)
437 self._transport = Transport(
438 credentials=credentials,
439 credentials_file=client_options.credentials_file,
440 host=api_endpoint,
441 scopes=client_options.scopes,
442 client_cert_source_for_mtls=client_cert_source_func,
443 quota_project_id=client_options.quota_project_id,
444 client_info=client_info,
445 always_use_jwt_access=True,
446 api_audience=client_options.api_audience,
447 )
449 def get_folder(
450 self,
451 request: Optional[Union[folders.GetFolderRequest, dict]] = None,
452 *,
453 name: Optional[str] = None,
454 retry: OptionalRetry = gapic_v1.method.DEFAULT,
455 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
456 metadata: Sequence[Tuple[str, str]] = (),
457 ) -> folders.Folder:
458 r"""Retrieves a folder identified by the supplied resource name.
459 Valid folder resource names have the format
460 ``folders/{folder_id}`` (for example, ``folders/1234``). The
461 caller must have ``resourcemanager.folders.get`` permission on
462 the identified folder.
464 .. code-block:: python
466 # This snippet has been automatically generated and should be regarded as a
467 # code template only.
468 # It will require modifications to work:
469 # - It may require correct/in-range values for request initialization.
470 # - It may require specifying regional endpoints when creating the service
471 # client as shown in:
472 # https://googleapis.dev/python/google-api-core/latest/client_options.html
473 from google.cloud import resourcemanager_v3
475 def sample_get_folder():
476 # Create a client
477 client = resourcemanager_v3.FoldersClient()
479 # Initialize request argument(s)
480 request = resourcemanager_v3.GetFolderRequest(
481 name="name_value",
482 )
484 # Make the request
485 response = client.get_folder(request=request)
487 # Handle the response
488 print(response)
490 Args:
491 request (Union[google.cloud.resourcemanager_v3.types.GetFolderRequest, dict]):
492 The request object. The GetFolder request message.
493 name (str):
494 Required. The resource name of the folder to retrieve.
495 Must be of the form ``folders/{folder_id}``.
497 This corresponds to the ``name`` field
498 on the ``request`` instance; if ``request`` is provided, this
499 should not be set.
500 retry (google.api_core.retry.Retry): Designation of what errors, if any,
501 should be retried.
502 timeout (float): The timeout for this request.
503 metadata (Sequence[Tuple[str, str]]): Strings which should be
504 sent along with the request as metadata.
506 Returns:
507 google.cloud.resourcemanager_v3.types.Folder:
508 A folder in an organization's
509 resource hierarchy, used to organize
510 that organization's resources.
512 """
513 # Create or coerce a protobuf request object.
514 # Quick check: If we got a request object, we should *not* have
515 # gotten any keyword arguments that map to the request.
516 has_flattened_params = any([name])
517 if request is not None and has_flattened_params:
518 raise ValueError(
519 "If the `request` argument is set, then none of "
520 "the individual field arguments should be set."
521 )
523 # Minor optimization to avoid making a copy if the user passes
524 # in a folders.GetFolderRequest.
525 # There's no risk of modifying the input as we've already verified
526 # there are no flattened fields.
527 if not isinstance(request, folders.GetFolderRequest):
528 request = folders.GetFolderRequest(request)
529 # If we have keyword arguments corresponding to fields on the
530 # request, apply these.
531 if name is not None:
532 request.name = name
534 # Wrap the RPC method; this adds retry and timeout information,
535 # and friendly error handling.
536 rpc = self._transport._wrapped_methods[self._transport.get_folder]
538 # Certain fields should be provided within the metadata header;
539 # add these here.
540 metadata = tuple(metadata) + (
541 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
542 )
544 # Send the request.
545 response = rpc(
546 request,
547 retry=retry,
548 timeout=timeout,
549 metadata=metadata,
550 )
552 # Done; return the response.
553 return response
555 def list_folders(
556 self,
557 request: Optional[Union[folders.ListFoldersRequest, dict]] = None,
558 *,
559 parent: Optional[str] = None,
560 retry: OptionalRetry = gapic_v1.method.DEFAULT,
561 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
562 metadata: Sequence[Tuple[str, str]] = (),
563 ) -> pagers.ListFoldersPager:
564 r"""Lists the folders that are direct descendants of supplied parent
565 resource. ``list()`` provides a strongly consistent view of the
566 folders underneath the specified parent resource. ``list()``
567 returns folders sorted based upon the (ascending) lexical
568 ordering of their display_name. The caller must have
569 ``resourcemanager.folders.list`` permission on the identified
570 parent.
572 .. code-block:: python
574 # This snippet has been automatically generated and should be regarded as a
575 # code template only.
576 # It will require modifications to work:
577 # - It may require correct/in-range values for request initialization.
578 # - It may require specifying regional endpoints when creating the service
579 # client as shown in:
580 # https://googleapis.dev/python/google-api-core/latest/client_options.html
581 from google.cloud import resourcemanager_v3
583 def sample_list_folders():
584 # Create a client
585 client = resourcemanager_v3.FoldersClient()
587 # Initialize request argument(s)
588 request = resourcemanager_v3.ListFoldersRequest(
589 parent="parent_value",
590 )
592 # Make the request
593 page_result = client.list_folders(request=request)
595 # Handle the response
596 for response in page_result:
597 print(response)
599 Args:
600 request (Union[google.cloud.resourcemanager_v3.types.ListFoldersRequest, dict]):
601 The request object. The ListFolders request message.
602 parent (str):
603 Required. The name of the parent resource whose folders
604 are being listed. Only children of this parent resource
605 are listed; descendants are not listed.
607 If the parent is a folder, use the value
608 ``folders/{folder_id}``. If the parent is an
609 organization, use the value ``organizations/{org_id}``.
611 Access to this method is controlled by checking the
612 ``resourcemanager.folders.list`` permission on the
613 ``parent``.
615 This corresponds to the ``parent`` field
616 on the ``request`` instance; if ``request`` is provided, this
617 should not be set.
618 retry (google.api_core.retry.Retry): Designation of what errors, if any,
619 should be retried.
620 timeout (float): The timeout for this request.
621 metadata (Sequence[Tuple[str, str]]): Strings which should be
622 sent along with the request as metadata.
624 Returns:
625 google.cloud.resourcemanager_v3.services.folders.pagers.ListFoldersPager:
626 The ListFolders response message.
627 Iterating over this object will yield
628 results and resolve additional pages
629 automatically.
631 """
632 # Create or coerce a protobuf request object.
633 # Quick check: If we got a request object, we should *not* have
634 # gotten any keyword arguments that map to the request.
635 has_flattened_params = any([parent])
636 if request is not None and has_flattened_params:
637 raise ValueError(
638 "If the `request` argument is set, then none of "
639 "the individual field arguments should be set."
640 )
642 # Minor optimization to avoid making a copy if the user passes
643 # in a folders.ListFoldersRequest.
644 # There's no risk of modifying the input as we've already verified
645 # there are no flattened fields.
646 if not isinstance(request, folders.ListFoldersRequest):
647 request = folders.ListFoldersRequest(request)
648 # If we have keyword arguments corresponding to fields on the
649 # request, apply these.
650 if parent is not None:
651 request.parent = parent
653 # Wrap the RPC method; this adds retry and timeout information,
654 # and friendly error handling.
655 rpc = self._transport._wrapped_methods[self._transport.list_folders]
657 # Send the request.
658 response = rpc(
659 request,
660 retry=retry,
661 timeout=timeout,
662 metadata=metadata,
663 )
665 # This method is paged; wrap the response in a pager, which provides
666 # an `__iter__` convenience method.
667 response = pagers.ListFoldersPager(
668 method=rpc,
669 request=request,
670 response=response,
671 metadata=metadata,
672 )
674 # Done; return the response.
675 return response
677 def search_folders(
678 self,
679 request: Optional[Union[folders.SearchFoldersRequest, dict]] = None,
680 *,
681 query: Optional[str] = None,
682 retry: OptionalRetry = gapic_v1.method.DEFAULT,
683 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
684 metadata: Sequence[Tuple[str, str]] = (),
685 ) -> pagers.SearchFoldersPager:
686 r"""Search for folders that match specific filter criteria.
687 ``search()`` provides an eventually consistent view of the
688 folders a user has access to which meet the specified filter
689 criteria.
691 This will only return folders on which the caller has the
692 permission ``resourcemanager.folders.get``.
694 .. code-block:: python
696 # This snippet has been automatically generated and should be regarded as a
697 # code template only.
698 # It will require modifications to work:
699 # - It may require correct/in-range values for request initialization.
700 # - It may require specifying regional endpoints when creating the service
701 # client as shown in:
702 # https://googleapis.dev/python/google-api-core/latest/client_options.html
703 from google.cloud import resourcemanager_v3
705 def sample_search_folders():
706 # Create a client
707 client = resourcemanager_v3.FoldersClient()
709 # Initialize request argument(s)
710 request = resourcemanager_v3.SearchFoldersRequest(
711 )
713 # Make the request
714 page_result = client.search_folders(request=request)
716 # Handle the response
717 for response in page_result:
718 print(response)
720 Args:
721 request (Union[google.cloud.resourcemanager_v3.types.SearchFoldersRequest, dict]):
722 The request object. The request message for searching
723 folders.
724 query (str):
725 Optional. Search criteria used to select the folders to
726 return. If no search criteria is specified then all
727 accessible folders will be returned.
729 Query expressions can be used to restrict results based
730 upon displayName, state and parent, where the operators
731 ``=`` (``:``) ``NOT``, ``AND`` and ``OR`` can be used
732 along with the suffix wildcard symbol ``*``.
734 The ``displayName`` field in a query expression should
735 use escaped quotes for values that include whitespace to
736 prevent unexpected behavior.
738 ::
740 | Field | Description |
741 |-------------------------|----------------------------------------|
742 | displayName | Filters by displayName. |
743 | parent | Filters by parent (for example: folders/123). |
744 | state, lifecycleState | Filters by state. |
746 Some example queries are:
748 - Query ``displayName=Test*`` returns Folder resources
749 whose display name starts with "Test".
750 - Query ``state=ACTIVE`` returns Folder resources with
751 ``state`` set to ``ACTIVE``.
752 - Query ``parent=folders/123`` returns Folder resources
753 that have ``folders/123`` as a parent resource.
754 - Query ``parent=folders/123 AND state=ACTIVE`` returns
755 active Folder resources that have ``folders/123`` as
756 a parent resource.
757 - Query ``displayName=\\"Test String\\"`` returns
758 Folder resources with display names that include both
759 "Test" and "String".
761 This corresponds to the ``query`` field
762 on the ``request`` instance; if ``request`` is provided, this
763 should not be set.
764 retry (google.api_core.retry.Retry): Designation of what errors, if any,
765 should be retried.
766 timeout (float): The timeout for this request.
767 metadata (Sequence[Tuple[str, str]]): Strings which should be
768 sent along with the request as metadata.
770 Returns:
771 google.cloud.resourcemanager_v3.services.folders.pagers.SearchFoldersPager:
772 The response message for searching
773 folders.
774 Iterating over this object will yield
775 results and resolve additional pages
776 automatically.
778 """
779 # Create or coerce a protobuf request object.
780 # Quick check: If we got a request object, we should *not* have
781 # gotten any keyword arguments that map to the request.
782 has_flattened_params = any([query])
783 if request is not None and has_flattened_params:
784 raise ValueError(
785 "If the `request` argument is set, then none of "
786 "the individual field arguments should be set."
787 )
789 # Minor optimization to avoid making a copy if the user passes
790 # in a folders.SearchFoldersRequest.
791 # There's no risk of modifying the input as we've already verified
792 # there are no flattened fields.
793 if not isinstance(request, folders.SearchFoldersRequest):
794 request = folders.SearchFoldersRequest(request)
795 # If we have keyword arguments corresponding to fields on the
796 # request, apply these.
797 if query is not None:
798 request.query = query
800 # Wrap the RPC method; this adds retry and timeout information,
801 # and friendly error handling.
802 rpc = self._transport._wrapped_methods[self._transport.search_folders]
804 # Send the request.
805 response = rpc(
806 request,
807 retry=retry,
808 timeout=timeout,
809 metadata=metadata,
810 )
812 # This method is paged; wrap the response in a pager, which provides
813 # an `__iter__` convenience method.
814 response = pagers.SearchFoldersPager(
815 method=rpc,
816 request=request,
817 response=response,
818 metadata=metadata,
819 )
821 # Done; return the response.
822 return response
824 def create_folder(
825 self,
826 request: Optional[Union[folders.CreateFolderRequest, dict]] = None,
827 *,
828 folder: Optional[folders.Folder] = None,
829 retry: OptionalRetry = gapic_v1.method.DEFAULT,
830 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
831 metadata: Sequence[Tuple[str, str]] = (),
832 ) -> operation.Operation:
833 r"""Creates a folder in the resource hierarchy. Returns an
834 ``Operation`` which can be used to track the progress of the
835 folder creation workflow. Upon success, the
836 ``Operation.response`` field will be populated with the created
837 Folder.
839 In order to succeed, the addition of this new folder must not
840 violate the folder naming, height, or fanout constraints.
842 - The folder's ``display_name`` must be distinct from all other
843 folders that share its parent.
844 - The addition of the folder must not cause the active folder
845 hierarchy to exceed a height of 10. Note, the full active +
846 deleted folder hierarchy is allowed to reach a height of 20;
847 this provides additional headroom when moving folders that
848 contain deleted folders.
849 - The addition of the folder must not cause the total number of
850 folders under its parent to exceed 300.
852 If the operation fails due to a folder constraint violation,
853 some errors may be returned by the ``CreateFolder`` request,
854 with status code ``FAILED_PRECONDITION`` and an error
855 description. Other folder constraint violations will be
856 communicated in the ``Operation``, with the specific
857 ``PreconditionFailure`` returned in the details list in the
858 ``Operation.error`` field.
860 The caller must have ``resourcemanager.folders.create``
861 permission on the identified parent.
863 .. code-block:: python
865 # This snippet has been automatically generated and should be regarded as a
866 # code template only.
867 # It will require modifications to work:
868 # - It may require correct/in-range values for request initialization.
869 # - It may require specifying regional endpoints when creating the service
870 # client as shown in:
871 # https://googleapis.dev/python/google-api-core/latest/client_options.html
872 from google.cloud import resourcemanager_v3
874 def sample_create_folder():
875 # Create a client
876 client = resourcemanager_v3.FoldersClient()
878 # Initialize request argument(s)
879 folder = resourcemanager_v3.Folder()
880 folder.parent = "parent_value"
882 request = resourcemanager_v3.CreateFolderRequest(
883 folder=folder,
884 )
886 # Make the request
887 operation = client.create_folder(request=request)
889 print("Waiting for operation to complete...")
891 response = operation.result()
893 # Handle the response
894 print(response)
896 Args:
897 request (Union[google.cloud.resourcemanager_v3.types.CreateFolderRequest, dict]):
898 The request object. The CreateFolder request message.
899 folder (google.cloud.resourcemanager_v3.types.Folder):
900 Required. The folder being created,
901 only the display name and parent will be
902 consulted. All other fields will be
903 ignored.
905 This corresponds to the ``folder`` field
906 on the ``request`` instance; if ``request`` is provided, this
907 should not be set.
908 retry (google.api_core.retry.Retry): Designation of what errors, if any,
909 should be retried.
910 timeout (float): The timeout for this request.
911 metadata (Sequence[Tuple[str, str]]): Strings which should be
912 sent along with the request as metadata.
914 Returns:
915 google.api_core.operation.Operation:
916 An object representing a long-running operation.
918 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
919 organize that organization's resources.
921 """
922 # Create or coerce a protobuf request object.
923 # Quick check: If we got a request object, we should *not* have
924 # gotten any keyword arguments that map to the request.
925 has_flattened_params = any([folder])
926 if request is not None and has_flattened_params:
927 raise ValueError(
928 "If the `request` argument is set, then none of "
929 "the individual field arguments should be set."
930 )
932 # Minor optimization to avoid making a copy if the user passes
933 # in a folders.CreateFolderRequest.
934 # There's no risk of modifying the input as we've already verified
935 # there are no flattened fields.
936 if not isinstance(request, folders.CreateFolderRequest):
937 request = folders.CreateFolderRequest(request)
938 # If we have keyword arguments corresponding to fields on the
939 # request, apply these.
940 if folder is not None:
941 request.folder = folder
943 # Wrap the RPC method; this adds retry and timeout information,
944 # and friendly error handling.
945 rpc = self._transport._wrapped_methods[self._transport.create_folder]
947 # Send the request.
948 response = rpc(
949 request,
950 retry=retry,
951 timeout=timeout,
952 metadata=metadata,
953 )
955 # Wrap the response in an operation future.
956 response = operation.from_gapic(
957 response,
958 self._transport.operations_client,
959 folders.Folder,
960 metadata_type=folders.CreateFolderMetadata,
961 )
963 # Done; return the response.
964 return response
966 def update_folder(
967 self,
968 request: Optional[Union[folders.UpdateFolderRequest, dict]] = None,
969 *,
970 folder: Optional[folders.Folder] = None,
971 update_mask: Optional[field_mask_pb2.FieldMask] = None,
972 retry: OptionalRetry = gapic_v1.method.DEFAULT,
973 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
974 metadata: Sequence[Tuple[str, str]] = (),
975 ) -> operation.Operation:
976 r"""Updates a folder, changing its ``display_name``. Changes to the
977 folder ``display_name`` will be rejected if they violate either
978 the ``display_name`` formatting rules or the naming constraints
979 described in the
980 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
981 documentation.
983 The folder's ``display_name`` must start and end with a letter
984 or digit, may contain letters, digits, spaces, hyphens and
985 underscores and can be between 3 and 30 characters. This is
986 captured by the regular expression:
987 ``[\p{L}\p{N}][\p{L}\p{N}_- ]{1,28}[\p{L}\p{N}]``. The caller
988 must have ``resourcemanager.folders.update`` permission on the
989 identified folder.
991 If the update fails due to the unique name constraint then a
992 ``PreconditionFailure`` explaining this violation will be
993 returned in the Status.details field.
995 .. code-block:: python
997 # This snippet has been automatically generated and should be regarded as a
998 # code template only.
999 # It will require modifications to work:
1000 # - It may require correct/in-range values for request initialization.
1001 # - It may require specifying regional endpoints when creating the service
1002 # client as shown in:
1003 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1004 from google.cloud import resourcemanager_v3
1006 def sample_update_folder():
1007 # Create a client
1008 client = resourcemanager_v3.FoldersClient()
1010 # Initialize request argument(s)
1011 folder = resourcemanager_v3.Folder()
1012 folder.parent = "parent_value"
1014 request = resourcemanager_v3.UpdateFolderRequest(
1015 folder=folder,
1016 )
1018 # Make the request
1019 operation = client.update_folder(request=request)
1021 print("Waiting for operation to complete...")
1023 response = operation.result()
1025 # Handle the response
1026 print(response)
1028 Args:
1029 request (Union[google.cloud.resourcemanager_v3.types.UpdateFolderRequest, dict]):
1030 The request object. The request sent to the
1031 [UpdateFolder][google.cloud.resourcemanager.v3.Folder.UpdateFolder]
1032 method.
1034 Only the ``display_name`` field can be changed. All
1035 other fields will be ignored. Use the
1036 [MoveFolder][google.cloud.resourcemanager.v3.Folders.MoveFolder]
1037 method to change the ``parent`` field.
1038 folder (google.cloud.resourcemanager_v3.types.Folder):
1039 Required. The new definition of the Folder. It must
1040 include the ``name`` field, which cannot be changed.
1042 This corresponds to the ``folder`` field
1043 on the ``request`` instance; if ``request`` is provided, this
1044 should not be set.
1045 update_mask (google.protobuf.field_mask_pb2.FieldMask):
1046 Required. Fields to be updated. Only the
1047 ``display_name`` can be updated.
1049 This corresponds to the ``update_mask`` field
1050 on the ``request`` instance; if ``request`` is provided, this
1051 should not be set.
1052 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1053 should be retried.
1054 timeout (float): The timeout for this request.
1055 metadata (Sequence[Tuple[str, str]]): Strings which should be
1056 sent along with the request as metadata.
1058 Returns:
1059 google.api_core.operation.Operation:
1060 An object representing a long-running operation.
1062 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
1063 organize that organization's resources.
1065 """
1066 # Create or coerce a protobuf request object.
1067 # Quick check: If we got a request object, we should *not* have
1068 # gotten any keyword arguments that map to the request.
1069 has_flattened_params = any([folder, update_mask])
1070 if request is not None and has_flattened_params:
1071 raise ValueError(
1072 "If the `request` argument is set, then none of "
1073 "the individual field arguments should be set."
1074 )
1076 # Minor optimization to avoid making a copy if the user passes
1077 # in a folders.UpdateFolderRequest.
1078 # There's no risk of modifying the input as we've already verified
1079 # there are no flattened fields.
1080 if not isinstance(request, folders.UpdateFolderRequest):
1081 request = folders.UpdateFolderRequest(request)
1082 # If we have keyword arguments corresponding to fields on the
1083 # request, apply these.
1084 if folder is not None:
1085 request.folder = folder
1086 if update_mask is not None:
1087 request.update_mask = update_mask
1089 # Wrap the RPC method; this adds retry and timeout information,
1090 # and friendly error handling.
1091 rpc = self._transport._wrapped_methods[self._transport.update_folder]
1093 # Certain fields should be provided within the metadata header;
1094 # add these here.
1095 metadata = tuple(metadata) + (
1096 gapic_v1.routing_header.to_grpc_metadata(
1097 (("folder.name", request.folder.name),)
1098 ),
1099 )
1101 # Send the request.
1102 response = rpc(
1103 request,
1104 retry=retry,
1105 timeout=timeout,
1106 metadata=metadata,
1107 )
1109 # Wrap the response in an operation future.
1110 response = operation.from_gapic(
1111 response,
1112 self._transport.operations_client,
1113 folders.Folder,
1114 metadata_type=folders.UpdateFolderMetadata,
1115 )
1117 # Done; return the response.
1118 return response
1120 def move_folder(
1121 self,
1122 request: Optional[Union[folders.MoveFolderRequest, dict]] = None,
1123 *,
1124 name: Optional[str] = None,
1125 destination_parent: Optional[str] = None,
1126 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1127 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1128 metadata: Sequence[Tuple[str, str]] = (),
1129 ) -> operation.Operation:
1130 r"""Moves a folder under a new resource parent. Returns an
1131 ``Operation`` which can be used to track the progress of the
1132 folder move workflow. Upon success, the ``Operation.response``
1133 field will be populated with the moved folder. Upon failure, a
1134 ``FolderOperationError`` categorizing the failure cause will be
1135 returned - if the failure occurs synchronously then the
1136 ``FolderOperationError`` will be returned in the
1137 ``Status.details`` field. If it occurs asynchronously, then the
1138 FolderOperation will be returned in the ``Operation.error``
1139 field. In addition, the ``Operation.metadata`` field will be
1140 populated with a ``FolderOperation`` message as an aid to
1141 stateless clients. Folder moves will be rejected if they violate
1142 either the naming, height, or fanout constraints described in
1143 the
1144 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
1145 documentation. The caller must have
1146 ``resourcemanager.folders.move`` permission on the folder's
1147 current and proposed new parent.
1149 .. code-block:: python
1151 # This snippet has been automatically generated and should be regarded as a
1152 # code template only.
1153 # It will require modifications to work:
1154 # - It may require correct/in-range values for request initialization.
1155 # - It may require specifying regional endpoints when creating the service
1156 # client as shown in:
1157 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1158 from google.cloud import resourcemanager_v3
1160 def sample_move_folder():
1161 # Create a client
1162 client = resourcemanager_v3.FoldersClient()
1164 # Initialize request argument(s)
1165 request = resourcemanager_v3.MoveFolderRequest(
1166 name="name_value",
1167 destination_parent="destination_parent_value",
1168 )
1170 # Make the request
1171 operation = client.move_folder(request=request)
1173 print("Waiting for operation to complete...")
1175 response = operation.result()
1177 # Handle the response
1178 print(response)
1180 Args:
1181 request (Union[google.cloud.resourcemanager_v3.types.MoveFolderRequest, dict]):
1182 The request object. The MoveFolder request message.
1183 name (str):
1184 Required. The resource name of the Folder to move. Must
1185 be of the form folders/{folder_id}
1187 This corresponds to the ``name`` field
1188 on the ``request`` instance; if ``request`` is provided, this
1189 should not be set.
1190 destination_parent (str):
1191 Required. The resource name of the folder or
1192 organization which should be the folder's new parent.
1193 Must be of the form ``folders/{folder_id}`` or
1194 ``organizations/{org_id}``.
1196 This corresponds to the ``destination_parent`` field
1197 on the ``request`` instance; if ``request`` is provided, this
1198 should not be set.
1199 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1200 should be retried.
1201 timeout (float): The timeout for this request.
1202 metadata (Sequence[Tuple[str, str]]): Strings which should be
1203 sent along with the request as metadata.
1205 Returns:
1206 google.api_core.operation.Operation:
1207 An object representing a long-running operation.
1209 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
1210 organize that organization's resources.
1212 """
1213 # Create or coerce a protobuf request object.
1214 # Quick check: If we got a request object, we should *not* have
1215 # gotten any keyword arguments that map to the request.
1216 has_flattened_params = any([name, destination_parent])
1217 if request is not None and has_flattened_params:
1218 raise ValueError(
1219 "If the `request` argument is set, then none of "
1220 "the individual field arguments should be set."
1221 )
1223 # Minor optimization to avoid making a copy if the user passes
1224 # in a folders.MoveFolderRequest.
1225 # There's no risk of modifying the input as we've already verified
1226 # there are no flattened fields.
1227 if not isinstance(request, folders.MoveFolderRequest):
1228 request = folders.MoveFolderRequest(request)
1229 # If we have keyword arguments corresponding to fields on the
1230 # request, apply these.
1231 if name is not None:
1232 request.name = name
1233 if destination_parent is not None:
1234 request.destination_parent = destination_parent
1236 # Wrap the RPC method; this adds retry and timeout information,
1237 # and friendly error handling.
1238 rpc = self._transport._wrapped_methods[self._transport.move_folder]
1240 # Certain fields should be provided within the metadata header;
1241 # add these here.
1242 metadata = tuple(metadata) + (
1243 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1244 )
1246 # Send the request.
1247 response = rpc(
1248 request,
1249 retry=retry,
1250 timeout=timeout,
1251 metadata=metadata,
1252 )
1254 # Wrap the response in an operation future.
1255 response = operation.from_gapic(
1256 response,
1257 self._transport.operations_client,
1258 folders.Folder,
1259 metadata_type=folders.MoveFolderMetadata,
1260 )
1262 # Done; return the response.
1263 return response
1265 def delete_folder(
1266 self,
1267 request: Optional[Union[folders.DeleteFolderRequest, dict]] = None,
1268 *,
1269 name: Optional[str] = None,
1270 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1271 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1272 metadata: Sequence[Tuple[str, str]] = (),
1273 ) -> operation.Operation:
1274 r"""Requests deletion of a folder. The folder is moved into the
1275 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1276 state immediately, and is deleted approximately 30 days later.
1277 This method may only be called on an empty folder, where a
1278 folder is empty if it doesn't contain any folders or projects in
1279 the
1280 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1281 state. If called on a folder in
1282 [DELETE_REQUESTED][google.cloud.resourcemanager.v3.Folder.State.DELETE_REQUESTED]
1283 state the operation will result in a no-op success. The caller
1284 must have ``resourcemanager.folders.delete`` permission on the
1285 identified folder.
1287 .. code-block:: python
1289 # This snippet has been automatically generated and should be regarded as a
1290 # code template only.
1291 # It will require modifications to work:
1292 # - It may require correct/in-range values for request initialization.
1293 # - It may require specifying regional endpoints when creating the service
1294 # client as shown in:
1295 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1296 from google.cloud import resourcemanager_v3
1298 def sample_delete_folder():
1299 # Create a client
1300 client = resourcemanager_v3.FoldersClient()
1302 # Initialize request argument(s)
1303 request = resourcemanager_v3.DeleteFolderRequest(
1304 name="name_value",
1305 )
1307 # Make the request
1308 operation = client.delete_folder(request=request)
1310 print("Waiting for operation to complete...")
1312 response = operation.result()
1314 # Handle the response
1315 print(response)
1317 Args:
1318 request (Union[google.cloud.resourcemanager_v3.types.DeleteFolderRequest, dict]):
1319 The request object. The DeleteFolder request message.
1320 name (str):
1321 Required. The resource name of the folder to be deleted.
1322 Must be of the form ``folders/{folder_id}``.
1324 This corresponds to the ``name`` field
1325 on the ``request`` instance; if ``request`` is provided, this
1326 should not be set.
1327 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1328 should be retried.
1329 timeout (float): The timeout for this request.
1330 metadata (Sequence[Tuple[str, str]]): Strings which should be
1331 sent along with the request as metadata.
1333 Returns:
1334 google.api_core.operation.Operation:
1335 An object representing a long-running operation.
1337 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
1338 organize that organization's resources.
1340 """
1341 # Create or coerce a protobuf request object.
1342 # Quick check: If we got a request object, we should *not* have
1343 # gotten any keyword arguments that map to the request.
1344 has_flattened_params = any([name])
1345 if request is not None and has_flattened_params:
1346 raise ValueError(
1347 "If the `request` argument is set, then none of "
1348 "the individual field arguments should be set."
1349 )
1351 # Minor optimization to avoid making a copy if the user passes
1352 # in a folders.DeleteFolderRequest.
1353 # There's no risk of modifying the input as we've already verified
1354 # there are no flattened fields.
1355 if not isinstance(request, folders.DeleteFolderRequest):
1356 request = folders.DeleteFolderRequest(request)
1357 # If we have keyword arguments corresponding to fields on the
1358 # request, apply these.
1359 if name is not None:
1360 request.name = name
1362 # Wrap the RPC method; this adds retry and timeout information,
1363 # and friendly error handling.
1364 rpc = self._transport._wrapped_methods[self._transport.delete_folder]
1366 # Certain fields should be provided within the metadata header;
1367 # add these here.
1368 metadata = tuple(metadata) + (
1369 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1370 )
1372 # Send the request.
1373 response = rpc(
1374 request,
1375 retry=retry,
1376 timeout=timeout,
1377 metadata=metadata,
1378 )
1380 # Wrap the response in an operation future.
1381 response = operation.from_gapic(
1382 response,
1383 self._transport.operations_client,
1384 folders.Folder,
1385 metadata_type=folders.DeleteFolderMetadata,
1386 )
1388 # Done; return the response.
1389 return response
1391 def undelete_folder(
1392 self,
1393 request: Optional[Union[folders.UndeleteFolderRequest, dict]] = None,
1394 *,
1395 name: Optional[str] = None,
1396 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1397 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1398 metadata: Sequence[Tuple[str, str]] = (),
1399 ) -> operation.Operation:
1400 r"""Cancels the deletion request for a folder. This method may be
1401 called on a folder in any state. If the folder is in the
1402 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1403 state the result will be a no-op success. In order to succeed,
1404 the folder's parent must be in the
1405 [ACTIVE][google.cloud.resourcemanager.v3.Folder.State.ACTIVE]
1406 state. In addition, reintroducing the folder into the tree must
1407 not violate folder naming, height, and fanout constraints
1408 described in the
1409 [CreateFolder][google.cloud.resourcemanager.v3.Folders.CreateFolder]
1410 documentation. The caller must have
1411 ``resourcemanager.folders.undelete`` permission on the
1412 identified folder.
1414 .. code-block:: python
1416 # This snippet has been automatically generated and should be regarded as a
1417 # code template only.
1418 # It will require modifications to work:
1419 # - It may require correct/in-range values for request initialization.
1420 # - It may require specifying regional endpoints when creating the service
1421 # client as shown in:
1422 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1423 from google.cloud import resourcemanager_v3
1425 def sample_undelete_folder():
1426 # Create a client
1427 client = resourcemanager_v3.FoldersClient()
1429 # Initialize request argument(s)
1430 request = resourcemanager_v3.UndeleteFolderRequest(
1431 name="name_value",
1432 )
1434 # Make the request
1435 operation = client.undelete_folder(request=request)
1437 print("Waiting for operation to complete...")
1439 response = operation.result()
1441 # Handle the response
1442 print(response)
1444 Args:
1445 request (Union[google.cloud.resourcemanager_v3.types.UndeleteFolderRequest, dict]):
1446 The request object. The UndeleteFolder request message.
1447 name (str):
1448 Required. The resource name of the folder to undelete.
1449 Must be of the form ``folders/{folder_id}``.
1451 This corresponds to the ``name`` field
1452 on the ``request`` instance; if ``request`` is provided, this
1453 should not be set.
1454 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1455 should be retried.
1456 timeout (float): The timeout for this request.
1457 metadata (Sequence[Tuple[str, str]]): Strings which should be
1458 sent along with the request as metadata.
1460 Returns:
1461 google.api_core.operation.Operation:
1462 An object representing a long-running operation.
1464 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
1465 organize that organization's resources.
1467 """
1468 # Create or coerce a protobuf request object.
1469 # Quick check: If we got a request object, we should *not* have
1470 # gotten any keyword arguments that map to the request.
1471 has_flattened_params = any([name])
1472 if request is not None and has_flattened_params:
1473 raise ValueError(
1474 "If the `request` argument is set, then none of "
1475 "the individual field arguments should be set."
1476 )
1478 # Minor optimization to avoid making a copy if the user passes
1479 # in a folders.UndeleteFolderRequest.
1480 # There's no risk of modifying the input as we've already verified
1481 # there are no flattened fields.
1482 if not isinstance(request, folders.UndeleteFolderRequest):
1483 request = folders.UndeleteFolderRequest(request)
1484 # If we have keyword arguments corresponding to fields on the
1485 # request, apply these.
1486 if name is not None:
1487 request.name = name
1489 # Wrap the RPC method; this adds retry and timeout information,
1490 # and friendly error handling.
1491 rpc = self._transport._wrapped_methods[self._transport.undelete_folder]
1493 # Certain fields should be provided within the metadata header;
1494 # add these here.
1495 metadata = tuple(metadata) + (
1496 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
1497 )
1499 # Send the request.
1500 response = rpc(
1501 request,
1502 retry=retry,
1503 timeout=timeout,
1504 metadata=metadata,
1505 )
1507 # Wrap the response in an operation future.
1508 response = operation.from_gapic(
1509 response,
1510 self._transport.operations_client,
1511 folders.Folder,
1512 metadata_type=folders.UndeleteFolderMetadata,
1513 )
1515 # Done; return the response.
1516 return response
1518 def get_iam_policy(
1519 self,
1520 request: Optional[Union[iam_policy_pb2.GetIamPolicyRequest, dict]] = None,
1521 *,
1522 resource: Optional[str] = None,
1523 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1524 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1525 metadata: Sequence[Tuple[str, str]] = (),
1526 ) -> policy_pb2.Policy:
1527 r"""Gets the access control policy for a folder. The returned policy
1528 may be empty if no such policy or resource exists. The
1529 ``resource`` field should be the folder's resource name, for
1530 example: "folders/1234". The caller must have
1531 ``resourcemanager.folders.getIamPolicy`` permission on the
1532 identified folder.
1534 .. code-block:: python
1536 # This snippet has been automatically generated and should be regarded as a
1537 # code template only.
1538 # It will require modifications to work:
1539 # - It may require correct/in-range values for request initialization.
1540 # - It may require specifying regional endpoints when creating the service
1541 # client as shown in:
1542 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1543 from google.cloud import resourcemanager_v3
1544 from google.iam.v1 import iam_policy_pb2 # type: ignore
1546 def sample_get_iam_policy():
1547 # Create a client
1548 client = resourcemanager_v3.FoldersClient()
1550 # Initialize request argument(s)
1551 request = iam_policy_pb2.GetIamPolicyRequest(
1552 resource="resource_value",
1553 )
1555 # Make the request
1556 response = client.get_iam_policy(request=request)
1558 # Handle the response
1559 print(response)
1561 Args:
1562 request (Union[google.iam.v1.iam_policy_pb2.GetIamPolicyRequest, dict]):
1563 The request object. Request message for ``GetIamPolicy`` method.
1564 resource (str):
1565 REQUIRED: The resource for which the
1566 policy is being requested. See the
1567 operation documentation for the
1568 appropriate value for this field.
1570 This corresponds to the ``resource`` field
1571 on the ``request`` instance; if ``request`` is provided, this
1572 should not be set.
1573 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1574 should be retried.
1575 timeout (float): The timeout for this request.
1576 metadata (Sequence[Tuple[str, str]]): Strings which should be
1577 sent along with the request as metadata.
1579 Returns:
1580 google.iam.v1.policy_pb2.Policy:
1581 An Identity and Access Management (IAM) policy, which specifies access
1582 controls for Google Cloud resources.
1584 A Policy is a collection of bindings. A binding binds
1585 one or more members, or principals, to a single role.
1586 Principals can be user accounts, service accounts,
1587 Google groups, and domains (such as G Suite). A role
1588 is a named list of permissions; each role can be an
1589 IAM predefined role or a user-created custom role.
1591 For some types of Google Cloud resources, a binding
1592 can also specify a condition, which is a logical
1593 expression that allows access to a resource only if
1594 the expression evaluates to true. A condition can add
1595 constraints based on attributes of the request, the
1596 resource, or both. To learn which resources support
1597 conditions in their IAM policies, see the [IAM
1598 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1600 **JSON example:**
1602 {
1603 "bindings": [
1604 {
1605 "role":
1606 "roles/resourcemanager.organizationAdmin",
1607 "members": [ "user:mike@example.com",
1608 "group:admins@example.com",
1609 "domain:google.com",
1610 "serviceAccount:my-project-id@appspot.gserviceaccount.com"
1611 ]
1613 }, { "role":
1614 "roles/resourcemanager.organizationViewer",
1615 "members": [ "user:eve@example.com" ],
1616 "condition": { "title": "expirable access",
1617 "description": "Does not grant access after
1618 Sep 2020", "expression": "request.time <
1619 timestamp('2020-10-01T00:00:00.000Z')", } }
1621 ], "etag": "BwWWja0YfJA=", "version": 3
1623 }
1625 **YAML example:**
1627 bindings: - members: - user:\ mike@example.com -
1628 group:\ admins@example.com - domain:google.com -
1629 serviceAccount:\ my-project-id@appspot.gserviceaccount.com
1630 role: roles/resourcemanager.organizationAdmin -
1631 members: - user:\ eve@example.com role:
1632 roles/resourcemanager.organizationViewer
1633 condition: title: expirable access description:
1634 Does not grant access after Sep 2020 expression:
1635 request.time <
1636 timestamp('2020-10-01T00:00:00.000Z') etag:
1637 BwWWja0YfJA= version: 3
1639 For a description of IAM and its features, see the
1640 [IAM
1641 documentation](\ https://cloud.google.com/iam/docs/).
1643 """
1644 # Create or coerce a protobuf request object.
1645 # Quick check: If we got a request object, we should *not* have
1646 # gotten any keyword arguments that map to the request.
1647 has_flattened_params = any([resource])
1648 if request is not None and has_flattened_params:
1649 raise ValueError(
1650 "If the `request` argument is set, then none of "
1651 "the individual field arguments should be set."
1652 )
1654 if isinstance(request, dict):
1655 # The request isn't a proto-plus wrapped type,
1656 # so it must be constructed via keyword expansion.
1657 request = iam_policy_pb2.GetIamPolicyRequest(**request)
1658 elif not request:
1659 # Null request, just make one.
1660 request = iam_policy_pb2.GetIamPolicyRequest()
1661 if resource is not None:
1662 request.resource = resource
1664 # Wrap the RPC method; this adds retry and timeout information,
1665 # and friendly error handling.
1666 rpc = self._transport._wrapped_methods[self._transport.get_iam_policy]
1668 # Certain fields should be provided within the metadata header;
1669 # add these here.
1670 metadata = tuple(metadata) + (
1671 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1672 )
1674 # Send the request.
1675 response = rpc(
1676 request,
1677 retry=retry,
1678 timeout=timeout,
1679 metadata=metadata,
1680 )
1682 # Done; return the response.
1683 return response
1685 def set_iam_policy(
1686 self,
1687 request: Optional[Union[iam_policy_pb2.SetIamPolicyRequest, dict]] = None,
1688 *,
1689 resource: Optional[str] = None,
1690 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1691 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1692 metadata: Sequence[Tuple[str, str]] = (),
1693 ) -> policy_pb2.Policy:
1694 r"""Sets the access control policy on a folder, replacing any
1695 existing policy. The ``resource`` field should be the folder's
1696 resource name, for example: "folders/1234". The caller must have
1697 ``resourcemanager.folders.setIamPolicy`` permission on the
1698 identified folder.
1700 .. code-block:: python
1702 # This snippet has been automatically generated and should be regarded as a
1703 # code template only.
1704 # It will require modifications to work:
1705 # - It may require correct/in-range values for request initialization.
1706 # - It may require specifying regional endpoints when creating the service
1707 # client as shown in:
1708 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1709 from google.cloud import resourcemanager_v3
1710 from google.iam.v1 import iam_policy_pb2 # type: ignore
1712 def sample_set_iam_policy():
1713 # Create a client
1714 client = resourcemanager_v3.FoldersClient()
1716 # Initialize request argument(s)
1717 request = iam_policy_pb2.SetIamPolicyRequest(
1718 resource="resource_value",
1719 )
1721 # Make the request
1722 response = client.set_iam_policy(request=request)
1724 # Handle the response
1725 print(response)
1727 Args:
1728 request (Union[google.iam.v1.iam_policy_pb2.SetIamPolicyRequest, dict]):
1729 The request object. Request message for ``SetIamPolicy`` method.
1730 resource (str):
1731 REQUIRED: The resource for which the
1732 policy is being specified. See the
1733 operation documentation for the
1734 appropriate value for this field.
1736 This corresponds to the ``resource`` field
1737 on the ``request`` instance; if ``request`` is provided, this
1738 should not be set.
1739 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1740 should be retried.
1741 timeout (float): The timeout for this request.
1742 metadata (Sequence[Tuple[str, str]]): Strings which should be
1743 sent along with the request as metadata.
1745 Returns:
1746 google.iam.v1.policy_pb2.Policy:
1747 An Identity and Access Management (IAM) policy, which specifies access
1748 controls for Google Cloud resources.
1750 A Policy is a collection of bindings. A binding binds
1751 one or more members, or principals, to a single role.
1752 Principals can be user accounts, service accounts,
1753 Google groups, and domains (such as G Suite). A role
1754 is a named list of permissions; each role can be an
1755 IAM predefined role or a user-created custom role.
1757 For some types of Google Cloud resources, a binding
1758 can also specify a condition, which is a logical
1759 expression that allows access to a resource only if
1760 the expression evaluates to true. A condition can add
1761 constraints based on attributes of the request, the
1762 resource, or both. To learn which resources support
1763 conditions in their IAM policies, see the [IAM
1764 documentation](\ https://cloud.google.com/iam/help/conditions/resource-policies).
1766 **JSON example:**
1768 {
1769 "bindings": [
1770 {
1771 "role":
1772 "roles/resourcemanager.organizationAdmin",
1773 "members": [ "user:mike@example.com",
1774 "group:admins@example.com",
1775 "domain:google.com",
1776 "serviceAccount:my-project-id@appspot.gserviceaccount.com"
1777 ]
1779 }, { "role":
1780 "roles/resourcemanager.organizationViewer",
1781 "members": [ "user:eve@example.com" ],
1782 "condition": { "title": "expirable access",
1783 "description": "Does not grant access after
1784 Sep 2020", "expression": "request.time <
1785 timestamp('2020-10-01T00:00:00.000Z')", } }
1787 ], "etag": "BwWWja0YfJA=", "version": 3
1789 }
1791 **YAML example:**
1793 bindings: - members: - user:\ mike@example.com -
1794 group:\ admins@example.com - domain:google.com -
1795 serviceAccount:\ my-project-id@appspot.gserviceaccount.com
1796 role: roles/resourcemanager.organizationAdmin -
1797 members: - user:\ eve@example.com role:
1798 roles/resourcemanager.organizationViewer
1799 condition: title: expirable access description:
1800 Does not grant access after Sep 2020 expression:
1801 request.time <
1802 timestamp('2020-10-01T00:00:00.000Z') etag:
1803 BwWWja0YfJA= version: 3
1805 For a description of IAM and its features, see the
1806 [IAM
1807 documentation](\ https://cloud.google.com/iam/docs/).
1809 """
1810 # Create or coerce a protobuf request object.
1811 # Quick check: If we got a request object, we should *not* have
1812 # gotten any keyword arguments that map to the request.
1813 has_flattened_params = any([resource])
1814 if request is not None and has_flattened_params:
1815 raise ValueError(
1816 "If the `request` argument is set, then none of "
1817 "the individual field arguments should be set."
1818 )
1820 if isinstance(request, dict):
1821 # The request isn't a proto-plus wrapped type,
1822 # so it must be constructed via keyword expansion.
1823 request = iam_policy_pb2.SetIamPolicyRequest(**request)
1824 elif not request:
1825 # Null request, just make one.
1826 request = iam_policy_pb2.SetIamPolicyRequest()
1827 if resource is not None:
1828 request.resource = resource
1830 # Wrap the RPC method; this adds retry and timeout information,
1831 # and friendly error handling.
1832 rpc = self._transport._wrapped_methods[self._transport.set_iam_policy]
1834 # Certain fields should be provided within the metadata header;
1835 # add these here.
1836 metadata = tuple(metadata) + (
1837 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1838 )
1840 # Send the request.
1841 response = rpc(
1842 request,
1843 retry=retry,
1844 timeout=timeout,
1845 metadata=metadata,
1846 )
1848 # Done; return the response.
1849 return response
1851 def test_iam_permissions(
1852 self,
1853 request: Optional[Union[iam_policy_pb2.TestIamPermissionsRequest, dict]] = None,
1854 *,
1855 resource: Optional[str] = None,
1856 permissions: Optional[MutableSequence[str]] = None,
1857 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1858 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1859 metadata: Sequence[Tuple[str, str]] = (),
1860 ) -> iam_policy_pb2.TestIamPermissionsResponse:
1861 r"""Returns permissions that a caller has on the specified folder.
1862 The ``resource`` field should be the folder's resource name, for
1863 example: "folders/1234".
1865 There are no permissions required for making this API call.
1867 .. code-block:: python
1869 # This snippet has been automatically generated and should be regarded as a
1870 # code template only.
1871 # It will require modifications to work:
1872 # - It may require correct/in-range values for request initialization.
1873 # - It may require specifying regional endpoints when creating the service
1874 # client as shown in:
1875 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1876 from google.cloud import resourcemanager_v3
1877 from google.iam.v1 import iam_policy_pb2 # type: ignore
1879 def sample_test_iam_permissions():
1880 # Create a client
1881 client = resourcemanager_v3.FoldersClient()
1883 # Initialize request argument(s)
1884 request = iam_policy_pb2.TestIamPermissionsRequest(
1885 resource="resource_value",
1886 permissions=['permissions_value1', 'permissions_value2'],
1887 )
1889 # Make the request
1890 response = client.test_iam_permissions(request=request)
1892 # Handle the response
1893 print(response)
1895 Args:
1896 request (Union[google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest, dict]):
1897 The request object. Request message for ``TestIamPermissions`` method.
1898 resource (str):
1899 REQUIRED: The resource for which the
1900 policy detail is being requested. See
1901 the operation documentation for the
1902 appropriate value for this field.
1904 This corresponds to the ``resource`` field
1905 on the ``request`` instance; if ``request`` is provided, this
1906 should not be set.
1907 permissions (MutableSequence[str]):
1908 The set of permissions to check for the ``resource``.
1909 Permissions with wildcards (such as '*' or 'storage.*')
1910 are not allowed. For more information see `IAM
1911 Overview <https://cloud.google.com/iam/docs/overview#permissions>`__.
1913 This corresponds to the ``permissions`` field
1914 on the ``request`` instance; if ``request`` is provided, this
1915 should not be set.
1916 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1917 should be retried.
1918 timeout (float): The timeout for this request.
1919 metadata (Sequence[Tuple[str, str]]): Strings which should be
1920 sent along with the request as metadata.
1922 Returns:
1923 google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse:
1924 Response message for TestIamPermissions method.
1925 """
1926 # Create or coerce a protobuf request object.
1927 # Quick check: If we got a request object, we should *not* have
1928 # gotten any keyword arguments that map to the request.
1929 has_flattened_params = any([resource, permissions])
1930 if request is not None and has_flattened_params:
1931 raise ValueError(
1932 "If the `request` argument is set, then none of "
1933 "the individual field arguments should be set."
1934 )
1936 if isinstance(request, dict):
1937 # The request isn't a proto-plus wrapped type,
1938 # so it must be constructed via keyword expansion.
1939 request = iam_policy_pb2.TestIamPermissionsRequest(**request)
1940 elif not request:
1941 # Null request, just make one.
1942 request = iam_policy_pb2.TestIamPermissionsRequest()
1943 if resource is not None:
1944 request.resource = resource
1945 if permissions:
1946 request.permissions.extend(permissions)
1948 # Wrap the RPC method; this adds retry and timeout information,
1949 # and friendly error handling.
1950 rpc = self._transport._wrapped_methods[self._transport.test_iam_permissions]
1952 # Certain fields should be provided within the metadata header;
1953 # add these here.
1954 metadata = tuple(metadata) + (
1955 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
1956 )
1958 # Send the request.
1959 response = rpc(
1960 request,
1961 retry=retry,
1962 timeout=timeout,
1963 metadata=metadata,
1964 )
1966 # Done; return the response.
1967 return response
1969 def __enter__(self) -> "FoldersClient":
1970 return self
1972 def __exit__(self, type, value, traceback):
1973 """Releases underlying transport's resources.
1975 .. warning::
1976 ONLY use as a context manager if the transport is NOT shared
1977 with other clients! Exiting the with block will CLOSE the transport
1978 and may cause errors in other clients!
1979 """
1980 self.transport.close()
1982 def get_operation(
1983 self,
1984 request: Optional[operations_pb2.GetOperationRequest] = None,
1985 *,
1986 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1987 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1988 metadata: Sequence[Tuple[str, str]] = (),
1989 ) -> operations_pb2.Operation:
1990 r"""Gets the latest state of a long-running operation.
1992 Args:
1993 request (:class:`~.operations_pb2.GetOperationRequest`):
1994 The request object. Request message for
1995 `GetOperation` method.
1996 retry (google.api_core.retry.Retry): Designation of what errors,
1997 if any, should be retried.
1998 timeout (float): The timeout for this request.
1999 metadata (Sequence[Tuple[str, str]]): Strings which should be
2000 sent along with the request as metadata.
2001 Returns:
2002 ~.operations_pb2.Operation:
2003 An ``Operation`` object.
2004 """
2005 # Create or coerce a protobuf request object.
2006 # The request isn't a proto-plus wrapped type,
2007 # so it must be constructed via keyword expansion.
2008 if isinstance(request, dict):
2009 request = operations_pb2.GetOperationRequest(**request)
2011 # Wrap the RPC method; this adds retry and timeout information,
2012 # and friendly error handling.
2013 rpc = gapic_v1.method.wrap_method(
2014 self._transport.get_operation,
2015 default_timeout=None,
2016 client_info=DEFAULT_CLIENT_INFO,
2017 )
2019 # Certain fields should be provided within the metadata header;
2020 # add these here.
2021 metadata = tuple(metadata) + (
2022 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
2023 )
2025 # Send the request.
2026 response = rpc(
2027 request,
2028 retry=retry,
2029 timeout=timeout,
2030 metadata=metadata,
2031 )
2033 # Done; return the response.
2034 return response
2037DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
2038 gapic_version=package_version.__version__
2039)
2042__all__ = ("FoldersClient",)