1 // Copyright 2017 Google Inc.
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
17 package google.cloud.resourcemanager.v2;
19 import "google/api/annotations.proto";
20 import "google/iam/v1/iam_policy.proto";
21 import "google/iam/v1/policy.proto";
22 import "google/longrunning/operations.proto";
23 import "google/protobuf/field_mask.proto";
24 import "google/protobuf/timestamp.proto";
26 option go_package = "google.golang.org/genproto/googleapis/cloud/resourcemanager/v2;resourcemanager";
27 option java_multiple_files = true;
28 option java_outer_classname = "FoldersProto";
29 option java_package = "com.google.cloud.resourcemanager.v2";
30 option csharp_namespace = "Google.Cloud.ResourceManager.V2";
31 option php_namespace = "Google\\Cloud\\ResourceManager\\V2";
33 // Manages Cloud Resource Folders.
34 // Cloud Resource Folders can be used to organize the resources under an
35 // organization and to control the IAM policies applied to groups of resources.
37 // Lists the Folders that are direct descendants of supplied parent resource.
38 // List provides a strongly consistent view of the Folders underneath
39 // the specified parent resource.
40 // List returns Folders sorted based upon the (ascending) lexical ordering
41 // of their display_name.
42 // The caller must have `resourcemanager.folders.list` permission on the
44 rpc ListFolders(ListFoldersRequest) returns (ListFoldersResponse) {
45 option (google.api.http) = {
50 // Search for folders that match specific filter criteria.
51 // Search provides an eventually consistent view of the folders a user has
52 // access to which meet the specified filter criteria.
54 // This will only return folders on which the caller has the
55 // permission `resourcemanager.folders.get`.
56 rpc SearchFolders(SearchFoldersRequest) returns (SearchFoldersResponse) {
57 option (google.api.http) = {
58 post: "/v2/folders:search"
63 // Retrieves a Folder identified by the supplied resource name.
64 // Valid Folder resource names have the format `folders/{folder_id}`
65 // (for example, `folders/1234`).
66 // The caller must have `resourcemanager.folders.get` permission on the
68 rpc GetFolder(GetFolderRequest) returns (Folder) {
69 option (google.api.http) = {
70 get: "/v2/{name=folders/*}"
74 // Creates a Folder in the resource hierarchy.
75 // Returns an Operation which can be used to track the progress of the
76 // folder creation workflow.
77 // Upon success the Operation.response field will be populated with the
80 // In order to succeed, the addition of this new Folder must not violate
81 // the Folder naming, height or fanout constraints.
82 // + The Folder's display_name must be distinct from all other Folder's that
84 // + The addition of the Folder must not cause the active Folder hierarchy
85 // to exceed a height of 4. Note, the full active + deleted Folder hierarchy
86 // is allowed to reach a height of 8; this provides additional headroom when
87 // moving folders that contain deleted folders.
88 // + The addition of the Folder must not cause the total number of Folders
89 // under its parent to exceed 100.
91 // If the operation fails due to a folder constraint violation,
92 // a PreconditionFailure explaining the violation will be returned.
93 // If the failure occurs synchronously then the PreconditionFailure
94 // will be returned via the Status.details field and if it occurs
95 // asynchronously then the PreconditionFailure will be returned
96 // via the Operation.error field.
98 // The caller must have `resourcemanager.folders.create` permission on the
100 rpc CreateFolder(CreateFolderRequest) returns (google.longrunning.Operation) {
101 option (google.api.http) = {
107 // Updates a Folder, changing its display_name.
108 // Changes to the folder display_name will be rejected if they violate either
109 // the display_name formatting rules or naming constraints described in
110 // the [CreateFolder] documentation.
111 // + The Folder's display name must start and end with a letter or digit,
112 // may contain letters, digits, spaces, hyphens and underscores and can be
113 // no longer than 30 characters. This is captured by the regular expression:
114 // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,28}[\p{L}\p{N}])?.
115 // The caller must have `resourcemanager.folders.update` permission on the
116 // identified folder.
118 // If the update fails due to the unique name constraint then a
119 // PreconditionFailure explaining this violation will be returned
120 // in the Status.details field.
121 rpc UpdateFolder(UpdateFolderRequest) returns (Folder) {
122 option (google.api.http) = {
123 patch: "/v2/{folder.name=folders/*}"
128 // Moves a Folder under a new resource parent.
129 // Returns an Operation which can be used to track the progress of the
130 // folder move workflow.
131 // Upon success the Operation.response field will be populated with the
133 // Upon failure, a FolderOperationError categorizing the failure cause will
134 // be returned - if the failure occurs synchronously then the
135 // FolderOperationError will be returned via the Status.details field
136 // and if it occurs asynchronously then the FolderOperation will be returned
137 // via the the Operation.error field.
138 // In addition, the Operation.metadata field will be populated with a
139 // FolderOperation message as an aid to stateless clients.
140 // Folder moves will be rejected if they violate either the naming, height
141 // or fanout constraints described in the [CreateFolder] documentation.
142 // The caller must have `resourcemanager.folders.move` permission on the
143 // folder's current and proposed new parent.
144 rpc MoveFolder(MoveFolderRequest) returns (google.longrunning.Operation) {
145 option (google.api.http) = {
146 post: "/v2/{name=folders/*}:move"
151 // Requests deletion of a Folder. The Folder is moved into the
152 // [DELETE_REQUESTED] state immediately, and is deleted approximately 30 days
153 // later. This method may only be called on an empty Folder in the [ACTIVE]
154 // state, where a Folder is empty if it doesn't contain any Folders or
155 // Projects in the [ACTIVE] state.
156 // The caller must have `resourcemanager.folders.delete` permission on the
157 // identified folder.
158 rpc DeleteFolder(DeleteFolderRequest) returns (Folder) {
159 option (google.api.http) = {
160 delete: "/v2/{name=folders/*}"
164 // Cancels the deletion request for a Folder. This method may only be
165 // called on a Folder in the [DELETE_REQUESTED] state.
166 // In order to succeed, the Folder's parent must be in the [ACTIVE] state.
167 // In addition, reintroducing the folder into the tree must not violate
168 // folder naming, height and fanout constraints described in the
169 // [CreateFolder] documentation.
170 // The caller must have `resourcemanager.folders.undelete` permission on the
171 // identified folder.
172 rpc UndeleteFolder(UndeleteFolderRequest) returns (Folder) {
173 option (google.api.http) = {
174 post: "/v2/{name=folders/*}:undelete"
179 // Gets the access control policy for a Folder. The returned policy may be
180 // empty if no such policy or resource exists. The `resource` field should
181 // be the Folder's resource name, e.g. "folders/1234".
182 // The caller must have `resourcemanager.folders.getIamPolicy` permission
183 // on the identified folder.
184 rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)
185 returns (google.iam.v1.Policy) {
186 option (google.api.http) = {
187 post: "/v2/{resource=folders/*}:getIamPolicy"
192 // Sets the access control policy on a Folder, replacing any existing policy.
193 // The `resource` field should be the Folder's resource name, e.g.
195 // The caller must have `resourcemanager.folders.setIamPolicy` permission
196 // on the identified folder.
197 rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)
198 returns (google.iam.v1.Policy) {
199 option (google.api.http) = {
200 post: "/v2/{resource=folders/*}:setIamPolicy"
205 // Returns permissions that a caller has on the specified Folder.
206 // The `resource` field should be the Folder's resource name,
207 // e.g. "folders/1234".
209 // There are no permissions required for making this API call.
210 rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)
211 returns (google.iam.v1.TestIamPermissionsResponse) {
212 option (google.api.http) = {
213 post: "/v2/{resource=folders/*}:testIamPermissions"
219 // A Folder in an Organization's resource hierarchy, used to
220 // organize that Organization's resources.
222 // Folder lifecycle states.
223 enum LifecycleState {
224 // Unspecified state.
225 LIFECYCLE_STATE_UNSPECIFIED = 0;
227 // The normal and active state.
230 // The folder has been marked for deletion by the user.
231 DELETE_REQUESTED = 2;
234 // Output only. The resource name of the Folder.
235 // Its format is `folders/{folder_id}`, for example: "folders/1234".
238 // The Folder’s parent's resource name.
239 // Updates to the folder's parent must be performed via [MoveFolders].
242 // The folder’s display name.
243 // A folder’s display name must be unique amongst its siblings, e.g.
244 // no two folders with the same parent can share the same display name.
245 // The display name must start and end with a letter or digit, may contain
246 // letters, digits, spaces, hyphens and underscores and can be no longer
247 // than 30 characters. This is captured by the regular expression:
248 // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,28}[\p{L}\p{N}])?.
249 string display_name = 3;
251 // Output only. The lifecycle state of the folder.
252 // Updates to the lifecycle_state must be performed via
253 // [DeleteFolder] and [UndeleteFolder].
254 LifecycleState lifecycle_state = 4;
256 // Output only. Timestamp when the Folder was created. Assigned by the server.
257 google.protobuf.Timestamp create_time = 5;
259 // Output only. Timestamp when the Folder was last modified.
260 google.protobuf.Timestamp update_time = 6;
263 // The ListFolders request message.
264 message ListFoldersRequest {
265 // The resource name of the Organization or Folder whose Folders are
267 // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`.
268 // Access to this method is controlled by checking the
269 // `resourcemanager.folders.list` permission on the `parent`.
272 // The maximum number of Folders to return in the response.
273 // This field is optional.
276 // A pagination token returned from a previous call to `ListFolders`
277 // that indicates where this listing should continue from.
278 // This field is optional.
279 string page_token = 3;
281 // Controls whether Folders in the [DELETE_REQUESTED} state should
283 bool show_deleted = 4;
286 // The ListFolders response message.
287 message ListFoldersResponse {
288 // A possibly paginated list of Folders that are direct descendants of
289 // the specified parent resource.
290 repeated Folder folders = 1;
292 // A pagination token returned from a previous call to `ListFolders`
293 // that indicates from where listing should continue.
294 // This field is optional.
295 string next_page_token = 2;
298 // The request message for searching folders.
299 message SearchFoldersRequest {
300 // The maximum number of folders to return in the response.
301 // This field is optional.
304 // A pagination token returned from a previous call to `SearchFolders`
305 // that indicates from where search should continue.
306 // This field is optional.
307 string page_token = 2;
309 // Search criteria used to select the Folders to return.
310 // If no search criteria is specified then all accessible folders will be
313 // Query expressions can be used to restrict results based upon displayName,
314 // lifecycleState and parent, where the operators `=`, `NOT`, `AND` and `OR`
315 // can be used along with the suffix wildcard symbol `*`.
317 // Some example queries are:
318 // |Query|Description|
319 // |------|-----------|
320 // |displayName=Test*|Folders whose display name starts with "Test".|
321 // |lifecycleState=ACTIVE|Folders whose lifecycleState is ACTIVE.|
322 // |parent=folders/123|Folders whose parent is "folders/123".|
323 // |parent=folders/123 AND lifecycleState=ACTIVE|Active folders whose
324 // parent is "folders/123".|
328 // The response message for searching folders.
329 message SearchFoldersResponse {
330 // A possibly paginated folder search results.
331 // the specified parent resource.
332 repeated Folder folders = 1;
334 // A pagination token returned from a previous call to `SearchFolders`
335 // that indicates from where searching should continue.
336 // This field is optional.
337 string next_page_token = 2;
340 // The GetFolder request message.
341 message GetFolderRequest {
342 // The resource name of the Folder to retrieve.
343 // Must be of the form `folders/{folder_id}`.
347 // The CreateFolder request message.
348 message CreateFolderRequest {
349 // The resource name of the new Folder's parent.
350 // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`.
353 // The Folder being created, only the display name will be consulted.
354 // All other fields will be ignored.
358 // The MoveFolder request message.
359 message MoveFolderRequest {
360 // The resource name of the Folder to move.
361 // Must be of the form folders/{folder_id}
364 // The resource name of the Folder or Organization to reparent
366 // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`.
367 string destination_parent = 2;
370 // The request message for updating a folder's display name.
371 message UpdateFolderRequest {
372 // The new definition of the Folder. It must include a
373 // a `name` and `display_name` field. The other fields
377 // Fields to be updated.
378 // Only the `display_name` can be updated.
379 google.protobuf.FieldMask update_mask = 2;
382 // The DeleteFolder request message.
383 message DeleteFolderRequest {
384 // the resource name of the Folder to be deleted.
385 // Must be of the form `folders/{folder_id}`.
388 // Instructs DeleteFolderAction to delete a folder even when the folder is not
390 bool recursive_delete = 2;
393 // The UndeleteFolder request message.
394 message UndeleteFolderRequest {
395 // The resource name of the Folder to undelete.
396 // Must be of the form `folders/{folder_id}`.
400 // Metadata describing a long running folder operation
401 message FolderOperation {
402 // The type of operation that failed.
404 // Operation type not specified.
405 OPERATION_TYPE_UNSPECIFIED = 0;
407 // A create folder operation.
410 // A move folder operation.
414 // The display name of the folder.
415 string display_name = 1;
417 // The type of this operation.
418 OperationType operation_type = 2;
420 // The resource name of the folder's parent.
421 // Only applicable when the operation_type is MOVE.
422 string source_parent = 3;
424 // The resource name of the folder or organization we are either creating
425 // the folder under or moving the folder to.
426 string destination_parent = 4;