0
# Folders Management
1
2
Hierarchical organization and management of folders within Google Cloud organizations. Folders provide an intermediate grouping layer between organizations and projects, enabling flexible resource organization and inheritance of IAM policies and organization policies.
3
4
## Capabilities
5
6
### Folder Retrieval
7
8
Retrieve detailed information about a specific folder using its resource name.
9
10
```python { .api }
11
def get_folder(
12
self,
13
request: GetFolderRequest = None,
14
*,
15
name: str = None,
16
retry: OptionalRetry = gapic_v1.method.DEFAULT,
17
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
18
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
19
) -> Folder:
20
"""
21
Retrieves a folder identified by the specified resource name.
22
23
Args:
24
name (str): The resource name of the folder to retrieve.
25
Format: folders/{folder_id}
26
retry: Retry configuration for the request
27
timeout: Request timeout in seconds
28
metadata: Additional metadata to send with the request
29
30
Returns:
31
Folder: The requested folder resource
32
33
Raises:
34
google.api_core.exceptions.NotFound: If the folder doesn't exist
35
google.api_core.exceptions.PermissionDenied: If access is denied
36
"""
37
```
38
39
Usage example:
40
41
```python
42
from google.cloud.resourcemanager import FoldersClient
43
44
client = FoldersClient()
45
folder = client.get_folder(name="folders/123456789")
46
print(f"Folder: {folder.display_name} (Parent: {folder.parent})")
47
```
48
49
### Folder Listing
50
51
List all folders under a specified parent resource (organization or another folder).
52
53
```python { .api }
54
def list_folders(
55
self,
56
request: ListFoldersRequest = None,
57
*,
58
parent: str = None,
59
retry: OptionalRetry = gapic_v1.method.DEFAULT,
60
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
61
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
62
) -> pagers.ListFoldersPager:
63
"""
64
Lists folders that are direct children of the specified parent resource.
65
66
Args:
67
parent (str): The parent resource whose folders are to be listed.
68
Formats: organizations/{organization_id} or folders/{folder_id}
69
retry: Retry configuration for the request
70
timeout: Request timeout in seconds
71
metadata: Additional metadata to send with the request
72
73
Returns:
74
ListFoldersPager: An iterator over folders that automatically
75
handles pagination
76
"""
77
```
78
79
Usage example:
80
81
```python
82
client = FoldersClient()
83
84
# List all folders under an organization
85
for folder in client.list_folders(parent="organizations/123456789"):
86
print(f"Folder: {folder.display_name} ({folder.name})")
87
88
# List all folders under another folder
89
for folder in client.list_folders(parent="folders/parent-folder-id"):
90
print(f"Sub-folder: {folder.display_name}")
91
```
92
93
### Folder Search
94
95
Search for folders using flexible query expressions with support for filtering and sorting.
96
97
```python { .api }
98
def search_folders(
99
self,
100
request: SearchFoldersRequest = None,
101
*,
102
query: str = None,
103
retry: OptionalRetry = gapic_v1.method.DEFAULT,
104
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
105
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
106
) -> pagers.SearchFoldersPager:
107
"""
108
Search for folders using a flexible query language.
109
110
Args:
111
query (str): Query expression for filtering folders.
112
Examples: 'displayName:dev*', 'parent.id:123456789',
113
'lifecycleState:ACTIVE'
114
retry: Retry configuration for the request
115
timeout: Request timeout in seconds
116
metadata: Additional metadata to send with the request
117
118
Returns:
119
SearchFoldersPager: An iterator over matching folders
120
"""
121
```
122
123
Usage example:
124
125
```python
126
client = FoldersClient()
127
128
# Search for active folders with "dev" in the display name
129
for folder in client.search_folders(query="displayName:dev* AND lifecycleState:ACTIVE"):
130
print(f"Found: {folder.display_name} ({folder.name})")
131
```
132
133
### Folder Creation
134
135
Create new folders within the Google Cloud resource hierarchy. This is a long-running operation.
136
137
```python { .api }
138
def create_folder(
139
self,
140
request: CreateFolderRequest = None,
141
*,
142
folder: Folder = None,
143
retry: OptionalRetry = gapic_v1.method.DEFAULT,
144
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
145
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
146
) -> operation.Operation:
147
"""
148
Creates a new folder. This is a long-running operation.
149
150
Args:
151
folder (Folder): The folder resource to create
152
retry: Retry configuration for the request
153
timeout: Request timeout in seconds
154
metadata: Additional metadata to send with the request
155
156
Returns:
157
Operation: Long-running operation that resolves to the created Folder
158
"""
159
```
160
161
Usage example:
162
163
```python
164
from google.cloud.resourcemanager import FoldersClient
165
from google.cloud.resourcemanager_v3.types import Folder
166
167
client = FoldersClient()
168
169
new_folder = Folder(
170
display_name="Development Team",
171
parent="organizations/123456789"
172
)
173
174
operation = client.create_folder(folder=new_folder)
175
result = operation.result() # Wait for completion
176
print(f"Created folder: {result.display_name} ({result.name})")
177
```
178
179
### Folder Updates
180
181
Update folder attributes such as display name. This is a long-running operation.
182
183
```python { .api }
184
def update_folder(
185
self,
186
request: UpdateFolderRequest = None,
187
*,
188
folder: Folder = None,
189
update_mask: field_mask_pb2.FieldMask = None,
190
retry: OptionalRetry = gapic_v1.method.DEFAULT,
191
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
192
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
193
) -> operation.Operation:
194
"""
195
Updates the specified folder. This is a long-running operation.
196
197
Args:
198
folder (Folder): The folder resource with updated values
199
update_mask (FieldMask): Fields to update. If not provided,
200
all mutable fields are updated
201
retry: Retry configuration for the request
202
timeout: Request timeout in seconds
203
metadata: Additional metadata to send with the request
204
205
Returns:
206
Operation: Long-running operation that resolves to the updated Folder
207
"""
208
```
209
210
Usage example:
211
212
```python
213
from google.protobuf import field_mask_pb2
214
215
client = FoldersClient()
216
217
# Get existing folder
218
folder = client.get_folder(name="folders/123456789")
219
220
# Update display name
221
folder.display_name = "Updated Development Team"
222
223
# Specify which fields to update
224
update_mask = field_mask_pb2.FieldMask(paths=["display_name"])
225
226
operation = client.update_folder(
227
folder=folder,
228
update_mask=update_mask
229
)
230
result = operation.result()
231
print(f"Updated folder: {result.display_name}")
232
```
233
234
### Folder Movement
235
236
Move folders between different parent resources (organizations or other folders). This is a long-running operation.
237
238
```python { .api }
239
def move_folder(
240
self,
241
request: MoveFolderRequest = None,
242
*,
243
name: str = None,
244
destination_parent: str = None,
245
retry: OptionalRetry = gapic_v1.method.DEFAULT,
246
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
247
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
248
) -> operation.Operation:
249
"""
250
Moves a folder to a different parent resource. This is a long-running operation.
251
252
Args:
253
name (str): The resource name of the folder to move.
254
Format: folders/{folder_id}
255
destination_parent (str): The new parent resource.
256
Format: organizations/{org_id} or folders/{folder_id}
257
retry: Retry configuration for the request
258
timeout: Request timeout in seconds
259
metadata: Additional metadata to send with the request
260
261
Returns:
262
Operation: Long-running operation that resolves to the moved Folder
263
"""
264
```
265
266
Usage example:
267
268
```python
269
client = FoldersClient()
270
271
operation = client.move_folder(
272
name="folders/source-folder-id",
273
destination_parent="folders/destination-folder-id"
274
)
275
result = operation.result()
276
print(f"Moved folder to: {result.parent}")
277
```
278
279
### Folder Deletion
280
281
Mark folders for deletion. Folders are not immediately deleted but enter a pending deletion state. This is a long-running operation.
282
283
```python { .api }
284
def delete_folder(
285
self,
286
request: DeleteFolderRequest = None,
287
*,
288
name: str = None,
289
retry: OptionalRetry = gapic_v1.method.DEFAULT,
290
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
291
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
292
) -> operation.Operation:
293
"""
294
Marks the specified folder for deletion. This is a long-running operation.
295
296
The folder enters DELETE_REQUESTED state and will be deleted after a
297
retention period unless restored with undelete_folder.
298
299
Args:
300
name (str): The resource name of the folder to delete.
301
Format: folders/{folder_id}
302
retry: Retry configuration for the request
303
timeout: Request timeout in seconds
304
metadata: Additional metadata to send with the request
305
306
Returns:
307
Operation: Long-running operation with no return value
308
"""
309
```
310
311
### Folder Restoration
312
313
Restore folders that are in the deletion pending state. This is a long-running operation.
314
315
```python { .api }
316
def undelete_folder(
317
self,
318
request: UndeleteFolderRequest = None,
319
*,
320
name: str = None,
321
retry: OptionalRetry = gapic_v1.method.DEFAULT,
322
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
323
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
324
) -> operation.Operation:
325
"""
326
Restores a folder from the DELETE_REQUESTED state. This is a long-running operation.
327
328
Args:
329
name (str): The resource name of the folder to restore.
330
Format: folders/{folder_id}
331
retry: Retry configuration for the request
332
timeout: Request timeout in seconds
333
metadata: Additional metadata to send with the request
334
335
Returns:
336
Operation: Long-running operation that resolves to the restored Folder
337
"""
338
```
339
340
Usage example:
341
342
```python
343
client = FoldersClient()
344
345
# Delete a folder
346
delete_op = client.delete_folder(name="folders/123456789")
347
delete_op.result() # Wait for completion
348
349
# Later, restore the folder
350
restore_op = client.undelete_folder(name="folders/123456789")
351
restored_folder = restore_op.result()
352
print(f"Restored folder: {restored_folder.display_name}")
353
```
354
355
### IAM Policy Management
356
357
Manage IAM (Identity and Access Management) policies for folders, controlling who has access and what permissions they have.
358
359
```python { .api }
360
def get_iam_policy(
361
self,
362
request: iam_policy_pb2.GetIamPolicyRequest = None,
363
*,
364
resource: str = None,
365
retry: OptionalRetry = gapic_v1.method.DEFAULT,
366
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
367
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
368
) -> policy_pb2.Policy:
369
"""
370
Gets the IAM access control policy for a folder.
371
372
Args:
373
resource (str): Resource name of the folder.
374
Format: folders/{folder_id}
375
376
Returns:
377
Policy: The IAM policy for the folder
378
"""
379
380
def set_iam_policy(
381
self,
382
request: iam_policy_pb2.SetIamPolicyRequest = None,
383
*,
384
resource: str = None,
385
policy: policy_pb2.Policy = None,
386
retry: OptionalRetry = gapic_v1.method.DEFAULT,
387
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
388
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
389
) -> policy_pb2.Policy:
390
"""
391
Sets the IAM access control policy for a folder.
392
393
Args:
394
resource (str): Resource name of the folder
395
policy (Policy): The new IAM policy
396
397
Returns:
398
Policy: The updated IAM policy
399
"""
400
401
def test_iam_permissions(
402
self,
403
request: iam_policy_pb2.TestIamPermissionsRequest = None,
404
*,
405
resource: str = None,
406
permissions: MutableSequence[str] = None,
407
retry: OptionalRetry = gapic_v1.method.DEFAULT,
408
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
409
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
410
) -> iam_policy_pb2.TestIamPermissionsResponse:
411
"""
412
Tests the specified permissions against the IAM policy for a folder.
413
414
Args:
415
resource (str): Resource name of the folder
416
permissions (Sequence[str]): List of permissions to test
417
418
Returns:
419
TestIamPermissionsResponse: Results of the permission test
420
"""
421
```
422
423
## Types
424
425
```python { .api }
426
class Folder:
427
name: str # Resource name: folders/{folder_id}
428
parent: str # Parent resource: organizations/{id} or folders/{id}
429
display_name: str # Human-readable folder name
430
state: Folder.State # Current lifecycle state
431
create_time: timestamp_pb2.Timestamp # Creation timestamp
432
update_time: timestamp_pb2.Timestamp # Last update timestamp
433
delete_time: timestamp_pb2.Timestamp # Deletion timestamp (if deleted)
434
etag: str # Entity tag for optimistic concurrency
435
436
class State(proto.Enum):
437
STATE_UNSPECIFIED = 0
438
ACTIVE = 1
439
DELETE_REQUESTED = 2
440
441
# Request/Response types
442
class GetFolderRequest:
443
name: str
444
445
class ListFoldersRequest:
446
parent: str
447
page_token: str
448
page_size: int
449
show_deleted: bool
450
451
class ListFoldersResponse:
452
folders: MutableSequence[Folder]
453
next_page_token: str
454
455
class SearchFoldersRequest:
456
query: str
457
page_token: str
458
page_size: int
459
460
class SearchFoldersResponse:
461
folders: MutableSequence[Folder]
462
next_page_token: str
463
464
class CreateFolderRequest:
465
folder: Folder
466
467
class UpdateFolderRequest:
468
folder: Folder
469
update_mask: field_mask_pb2.FieldMask
470
471
class MoveFolderRequest:
472
name: str
473
destination_parent: str
474
475
class DeleteFolderRequest:
476
name: str
477
478
class UndeleteFolderRequest:
479
name: str
480
481
# Metadata types for long-running operations
482
class CreateFolderMetadata:
483
display_name: str
484
parent: str
485
486
class UpdateFolderMetadata:
487
# Empty metadata message
488
489
class MoveFolderMetadata:
490
# Empty metadata message
491
492
class DeleteFolderMetadata:
493
# Empty metadata message
494
495
class UndeleteFolderMetadata:
496
# Empty metadata message
497
```