Google Cloud Storage Control

1.11.0 · active · verified Thu Apr 09

The `google-cloud-storage-control` library provides a Python client for interacting with the Google Cloud Storage Control API. This API allows for programmatic management of Storage features like Managed Folders and other bucket-level controls. It is currently at version 1.11.0 and is part of the larger `google-cloud-python` monorepo, receiving frequent updates along with other Google Cloud client libraries.

Warnings

breaking The `google-cloud-storage-control` library transitioned from version `0.x.x` to `1.x.x` (released 2023-08-09). This major version bump primarily adopted the Storage Control API v2. Users migrating from `0.x.x` might encounter breaking changes in client initialization, method signatures, and resource representations.
Fix: Upgrade to `google-cloud-storage-control>=1.0.0` and consult the official changelog for specific migration steps. Re-evaluate client instantiation and method calls to align with the `v2` API.
gotcha Managed Folders are a new feature and require specific IAM permissions beyond standard bucket access. Incorrect or insufficient permissions can lead to `PermissionDenied` errors.
Fix: Ensure the service account or user making the request has the necessary Storage Control permissions, such as `roles/storage.admin` or custom roles with granular permissions for `managedFolders.create`, `managedFolders.get`, `managedFolders.list`, `managedFolders.delete`.
gotcha Resource paths for operations (e.g., `parent` for `list_managed_folders`) must follow a strict format like `projects/{project_id}/buckets/{bucket_name}`.
Fix: Always construct resource paths using the exact `projects/{project_id}/buckets/{bucket_name}` pattern, or other specific resource patterns as documented for each method, to avoid `Invalid argument` errors.

Install

pip install google-cloud-storage-control Install stable version

Imports

StorageControlClient

from google.cloud.storage_control_v2 import StorageControlClient

ManagedFolder
```
from google.cloud.storage_control_v2.types import ManagedFolder
```
Always specify the API version (e.g., '_v2') for types if the client library supports multiple versions, even if only one is current. While `google.cloud.storage_control` might resolve in some cases, `_v2` is explicit and safer for future compatibility.

Quickstart

This quickstart demonstrates how to initialize the `StorageControlClient` and list managed folders within a specified Google Cloud Storage bucket. Ensure your `GOOGLE_CLOUD_PROJECT` and `GCS_BUCKET_NAME` environment variables are set, and your environment is authenticated (e.g., via `gcloud auth application-default login`).

import os
from google.cloud.storage_control_v2 import StorageControlClient

project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
bucket_name = os.environ.get('GCS_BUCKET_NAME', 'your-gcs-bucket-name')

if project_id == 'your-gcp-project-id':
    print("Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.")
    exit()
if bucket_name == 'your-gcs-bucket-name':
    print("Please set the GCS_BUCKET_NAME environment variable or replace 'your-gcs-bucket-name'.")
    exit()

client = StorageControlClient()

parent_path = f"projects/{project_id}/buckets/{bucket_name}"

try:
    # List managed folders in a bucket
    print(f"Listing managed folders in {parent_path}:")
    for managed_folder in client.list_managed_folders(parent=parent_path):
        print(f"- {managed_folder.name}")
except Exception as e:
    print(f"Error listing managed folders: {e}")
    print("Ensure you have appropriate IAM permissions (e.g., 'roles/storage.admin') for the bucket and that Application Default Credentials are configured.")

view raw JSON →