Struct Folders

pub struct Folders { /* private fields */ }

Implements a client for the Cloud Resource Manager API.

Service Description

Manages Cloud Platform folder resources. Folders can be used to organize the resources under an organization and to control the policies applied to groups of resources.

Configuration

Folders has various configuration parameters, the defaults should work with most applications.

Pooling and Cloning

Folders holds a connection pool internally, it is advised to create one and the reuse it. You do not need to wrap Folders in an Rc or Arc to reuse it, because it already uses an Arc internally.

Implementations

impl Folders

pub async fn new() -> Result<Self>

Creates a new client with the default configuration.

pub async fn new_with_config(conf: ClientConfig) -> Result<Self>

Creates a new client with the specified configuration.

pub fn from_stub<T>(stub: T) -> Self

where T: Folders + 'static,

Creates a new client from the provided stub.

The most common case for calling this function is when mocking the client.

pub fn get_folder(&self, name: impl Into<String>) -> GetFolder

Retrieves a folder identified by the supplied resource name. Valid folder resource names have the format folders/{folder_id} (for example, folders/1234). The caller must have resourcemanager.folders.get permission on the identified folder.

pub fn list_folders(&self) -> ListFolders

Lists the folders that are direct descendants of supplied parent resource. list() provides a strongly consistent view of the folders underneath the specified parent resource. list() returns folders sorted based upon the (ascending) lexical ordering of their display_name. The caller must have resourcemanager.folders.list permission on the identified parent.

pub fn search_folders(&self) -> SearchFolders

Search for folders that match specific filter criteria. search() provides an eventually consistent view of the folders a user has access to which meet the specified filter criteria.

This will only return folders on which the caller has the permission resourcemanager.folders.get.

pub fn create_folder(&self) -> CreateFolder

Creates a folder in the resource hierarchy. Returns an Operation which can be used to track the progress of the folder creation workflow. Upon success, the Operation.response field will be populated with the created Folder.

In order to succeed, the addition of this new folder must not violate the folder naming, height, or fanout constraints.

• The folder’s display_name must be distinct from all other folders that share its parent.
• The addition of the folder must not cause the active folder hierarchy to exceed a height of 10. Note, the full active + deleted folder hierarchy is allowed to reach a height of 20; this provides additional headroom when moving folders that contain deleted folders.
• The addition of the folder must not cause the total number of folders under its parent to exceed 300.

If the operation fails due to a folder constraint violation, some errors may be returned by the CreateFolder request, with status code FAILED_PRECONDITION and an error description. Other folder constraint violations will be communicated in the Operation, with the specific PreconditionFailure returned in the details list in the Operation.error field.

The caller must have resourcemanager.folders.create permission on the identified parent.

Long running operations

Calling poller() on the resulting builder returns an implementation of the lro::Poller trait. You need to call Poller::poll on this Poller at least once to start the LRO. You may periodically poll this object to find the status of the operation. The poller automatically extract the final response value and any intermediate metadata values.

Calling send() on the resulting builder starts a LRO (long-Running Operation). LROs run in the background, and the application may poll them periodically to find out if they have succeeded, or failed. See below for instructions on how to manually use the resulting Operation. We recommend poller() in favor of send().

Polling until completion

Applications that do not care about intermediate results in a long-running operation may use the until_done() function:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::CreateFolderMetadata>
) -> Result<model::Folder> {
    poller.until_done().await
}

This will wait until the LRO completes (successfully or with an error). Applications can set the PollingPolicy and PollingBackoffPolicy to control for how long the function runs.

Polling with detailed metadata updates

Using the result of poller() follows a common pattern:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::CreateFolderMetadata>
) -> Result<model::Folder> {
    while let Some(p) = poller.poll().await {
        match p {
            lro::PollingResult::Completed(r) => { return r; },
            lro::PollingResult::InProgress(m) => { println!("in progress {m:?}"); },
            lro::PollingResult::PollingError(_) => { /* ignored */ },
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
    Err(gax::error::Error::other("LRO never completed"))
}

Manually polling long-running operations

If you call send(), you need to examine the contents of the resulting Operation to determine the result of the operation.

If the done field is true, the operation has completed. The result field contains the final response, this will be a crate::model::Folder (as an Any), or the error (as a Status).

If the done field is false, the operation has not completed. The operation may also include a crate::model::CreateFolderMetadata value in the metadata field. This value would also be encoded as an Any. The metadata may include information about how much progress the LRO has made.

To find out if the operation has completed, use the get_operation method and repeat the steps outlined above.

Note that most errors on get_operation do not indicate that the long-running operation failed. Long-running operation failures return the error status in the result field.

pub fn update_folder(&self, folder: impl Into<Folder>) -> UpdateFolder

Updates a folder, changing its display_name. Changes to the folder display_name will be rejected if they violate either the display_name formatting rules or the naming constraints described in the CreateFolder documentation.

The folder’s display_name must start and end with a letter or digit, may contain letters, digits, spaces, hyphens and underscores and can be between 3 and 30 characters. This is captured by the regular expression: [\p{L}\p{N}][\p{L}\p{N}_- ]{1,28}[\p{L}\p{N}]. The caller must have resourcemanager.folders.update permission on the identified folder.

If the update fails due to the unique name constraint then a PreconditionFailure explaining this violation will be returned in the Status.details field.

Long running operations

Calling poller() on the resulting builder returns an implementation of the lro::Poller trait. You need to call Poller::poll on this Poller at least once to start the LRO. You may periodically poll this object to find the status of the operation. The poller automatically extract the final response value and any intermediate metadata values.

Calling send() on the resulting builder starts a LRO (long-Running Operation). LROs run in the background, and the application may poll them periodically to find out if they have succeeded, or failed. See below for instructions on how to manually use the resulting Operation. We recommend poller() in favor of send().

Polling until completion

Applications that do not care about intermediate results in a long-running operation may use the until_done() function:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::UpdateFolderMetadata>
) -> Result<model::Folder> {
    poller.until_done().await
}

This will wait until the LRO completes (successfully or with an error). Applications can set the PollingPolicy and PollingBackoffPolicy to control for how long the function runs.

Polling with detailed metadata updates

Using the result of poller() follows a common pattern:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::UpdateFolderMetadata>
) -> Result<model::Folder> {
    while let Some(p) = poller.poll().await {
        match p {
            lro::PollingResult::Completed(r) => { return r; },
            lro::PollingResult::InProgress(m) => { println!("in progress {m:?}"); },
            lro::PollingResult::PollingError(_) => { /* ignored */ },
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
    Err(gax::error::Error::other("LRO never completed"))
}

Manually polling long-running operations

If you call send(), you need to examine the contents of the resulting Operation to determine the result of the operation.

If the done field is true, the operation has completed. The result field contains the final response, this will be a crate::model::Folder (as an Any), or the error (as a Status).

If the done field is false, the operation has not completed. The operation may also include a crate::model::UpdateFolderMetadata value in the metadata field. This value would also be encoded as an Any. The metadata may include information about how much progress the LRO has made.

To find out if the operation has completed, use the get_operation method and repeat the steps outlined above.

Note that most errors on get_operation do not indicate that the long-running operation failed. Long-running operation failures return the error status in the result field.

pub fn move_folder(&self, name: impl Into<String>) -> MoveFolder

Moves a folder under a new resource parent. Returns an Operation which can be used to track the progress of the folder move workflow. Upon success, the Operation.response field will be populated with the moved folder. Upon failure, a FolderOperationError categorizing the failure cause will be returned - if the failure occurs synchronously then the FolderOperationError will be returned in the Status.details field. If it occurs asynchronously, then the FolderOperation will be returned in the Operation.error field. In addition, the Operation.metadata field will be populated with a FolderOperation message as an aid to stateless clients. Folder moves will be rejected if they violate either the naming, height, or fanout constraints described in the CreateFolder documentation. The caller must have resourcemanager.folders.move permission on the folder’s current and proposed new parent.

Long running operations

Calling poller() on the resulting builder returns an implementation of the lro::Poller trait. You need to call Poller::poll on this Poller at least once to start the LRO. You may periodically poll this object to find the status of the operation. The poller automatically extract the final response value and any intermediate metadata values.

Calling send() on the resulting builder starts a LRO (long-Running Operation). LROs run in the background, and the application may poll them periodically to find out if they have succeeded, or failed. See below for instructions on how to manually use the resulting Operation. We recommend poller() in favor of send().

Polling until completion

Applications that do not care about intermediate results in a long-running operation may use the until_done() function:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::MoveFolderMetadata>
) -> Result<model::Folder> {
    poller.until_done().await
}

This will wait until the LRO completes (successfully or with an error). Applications can set the PollingPolicy and PollingBackoffPolicy to control for how long the function runs.

Polling with detailed metadata updates

Using the result of poller() follows a common pattern:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::MoveFolderMetadata>
) -> Result<model::Folder> {
    while let Some(p) = poller.poll().await {
        match p {
            lro::PollingResult::Completed(r) => { return r; },
            lro::PollingResult::InProgress(m) => { println!("in progress {m:?}"); },
            lro::PollingResult::PollingError(_) => { /* ignored */ },
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
    Err(gax::error::Error::other("LRO never completed"))
}

Manually polling long-running operations

If you call send(), you need to examine the contents of the resulting Operation to determine the result of the operation.

If the done field is true, the operation has completed. The result field contains the final response, this will be a crate::model::Folder (as an Any), or the error (as a Status).

If the done field is false, the operation has not completed. The operation may also include a crate::model::MoveFolderMetadata value in the metadata field. This value would also be encoded as an Any. The metadata may include information about how much progress the LRO has made.

To find out if the operation has completed, use the get_operation method and repeat the steps outlined above.

Note that most errors on get_operation do not indicate that the long-running operation failed. Long-running operation failures return the error status in the result field.

pub fn delete_folder(&self, name: impl Into<String>) -> DeleteFolder

Requests deletion of a folder. The folder is moved into the DELETE_REQUESTED state immediately, and is deleted approximately 30 days later. This method may only be called on an empty folder, where a folder is empty if it doesn’t contain any folders or projects in the ACTIVE state. If called on a folder in DELETE_REQUESTED state the operation will result in a no-op success. The caller must have resourcemanager.folders.delete permission on the identified folder.

Long running operations

Calling poller() on the resulting builder returns an implementation of the lro::Poller trait. You need to call Poller::poll on this Poller at least once to start the LRO. You may periodically poll this object to find the status of the operation. The poller automatically extract the final response value and any intermediate metadata values.

Calling send() on the resulting builder starts a LRO (long-Running Operation). LROs run in the background, and the application may poll them periodically to find out if they have succeeded, or failed. See below for instructions on how to manually use the resulting Operation. We recommend poller() in favor of send().

Polling until completion

Applications that do not care about intermediate results in a long-running operation may use the until_done() function:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::DeleteFolderMetadata>
) -> Result<model::Folder> {
    poller.until_done().await
}

This will wait until the LRO completes (successfully or with an error). Applications can set the PollingPolicy and PollingBackoffPolicy to control for how long the function runs.

Polling with detailed metadata updates

Using the result of poller() follows a common pattern:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::DeleteFolderMetadata>
) -> Result<model::Folder> {
    while let Some(p) = poller.poll().await {
        match p {
            lro::PollingResult::Completed(r) => { return r; },
            lro::PollingResult::InProgress(m) => { println!("in progress {m:?}"); },
            lro::PollingResult::PollingError(_) => { /* ignored */ },
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
    Err(gax::error::Error::other("LRO never completed"))
}

Manually polling long-running operations

If you call send(), you need to examine the contents of the resulting Operation to determine the result of the operation.

If the done field is true, the operation has completed. The result field contains the final response, this will be a crate::model::Folder (as an Any), or the error (as a Status).

If the done field is false, the operation has not completed. The operation may also include a crate::model::DeleteFolderMetadata value in the metadata field. This value would also be encoded as an Any. The metadata may include information about how much progress the LRO has made.

To find out if the operation has completed, use the get_operation method and repeat the steps outlined above.

Note that most errors on get_operation do not indicate that the long-running operation failed. Long-running operation failures return the error status in the result field.

pub fn undelete_folder(&self, name: impl Into<String>) -> UndeleteFolder

Cancels the deletion request for a folder. This method may be called on a folder in any state. If the folder is in the ACTIVE state the result will be a no-op success. In order to succeed, the folder’s parent must be in the ACTIVE state. In addition, reintroducing the folder into the tree must not violate folder naming, height, and fanout constraints described in the CreateFolder documentation. The caller must have resourcemanager.folders.undelete permission on the identified folder.

Long running operations

Calling poller() on the resulting builder returns an implementation of the lro::Poller trait. You need to call Poller::poll on this Poller at least once to start the LRO. You may periodically poll this object to find the status of the operation. The poller automatically extract the final response value and any intermediate metadata values.

Calling send() on the resulting builder starts a LRO (long-Running Operation). LROs run in the background, and the application may poll them periodically to find out if they have succeeded, or failed. See below for instructions on how to manually use the resulting Operation. We recommend poller() in favor of send().

Polling until completion

Applications that do not care about intermediate results in a long-running operation may use the until_done() function:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::UndeleteFolderMetadata>
) -> Result<model::Folder> {
    poller.until_done().await
}

This will wait until the LRO completes (successfully or with an error). Applications can set the PollingPolicy and PollingBackoffPolicy to control for how long the function runs.

Polling with detailed metadata updates

Using the result of poller() follows a common pattern:

async fn wait(
    mut poller: impl lro::Poller<model::Folder, model::UndeleteFolderMetadata>
) -> Result<model::Folder> {
    while let Some(p) = poller.poll().await {
        match p {
            lro::PollingResult::Completed(r) => { return r; },
            lro::PollingResult::InProgress(m) => { println!("in progress {m:?}"); },
            lro::PollingResult::PollingError(_) => { /* ignored */ },
        }
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
    Err(gax::error::Error::other("LRO never completed"))
}

Manually polling long-running operations

If you call send(), you need to examine the contents of the resulting Operation to determine the result of the operation.

If the done field is true, the operation has completed. The result field contains the final response, this will be a crate::model::Folder (as an Any), or the error (as a Status).

If the done field is false, the operation has not completed. The operation may also include a crate::model::UndeleteFolderMetadata value in the metadata field. This value would also be encoded as an Any. The metadata may include information about how much progress the LRO has made.

To find out if the operation has completed, use the get_operation method and repeat the steps outlined above.

Note that most errors on get_operation do not indicate that the long-running operation failed. Long-running operation failures return the error status in the result field.

pub fn get_iam_policy(&self, resource: impl Into<String>) -> GetIamPolicy

Gets the access control policy for a folder. The returned policy may be empty if no such policy or resource exists. The resource field should be the folder’s resource name, for example: “folders/1234”. The caller must have resourcemanager.folders.getIamPolicy permission on the identified folder.

pub fn set_iam_policy(&self, resource: impl Into<String>) -> SetIamPolicy

Sets the access control policy on a folder, replacing any existing policy. The resource field should be the folder’s resource name, for example: “folders/1234”. The caller must have resourcemanager.folders.setIamPolicy permission on the identified folder.

pub fn test_iam_permissions( &self, resource: impl Into<String>, ) -> TestIamPermissions

Returns permissions that a caller has on the specified folder. The resource field should be the folder’s resource name, for example: “folders/1234”.

There are no permissions required for making this API call.

pub fn get_operation(&self, name: impl Into<String>) -> GetOperation

Provides the Operations service functionality in this service.

Trait Implementations

impl Clone for Folders

fn clone(&self) -> Folders

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Folders

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.