{"id":1497,"library":"google-cloud-storage-control","title":"Google Cloud Storage Control","description":"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.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-storage-control","tags":["google cloud","storage","cloud storage","managed folders","gcs","gcp"],"install":[{"cmd":"pip install google-cloud-storage-control","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionalities for Google APIs, including gRPC/REST transport.","package":"google-api-core"},{"reason":"Handles authentication to Google Cloud services.","package":"google-auth"},{"reason":"Shared components for Google Cloud client libraries.","package":"google-cloud-core"},{"reason":"Provides Pythonic wrappers for Protocol Buffer messages.","package":"proto-plus"},{"reason":"Core Protocol Buffers library.","package":"protobuf"}],"imports":[{"symbol":"StorageControlClient","correct":"from google.cloud.storage_control_v2 import StorageControlClient"},{"note":"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.","wrong":"from google.cloud.storage_control.types import ManagedFolder","symbol":"ManagedFolder","correct":"from google.cloud.storage_control_v2.types import ManagedFolder"}],"quickstart":{"code":"import os\nfrom google.cloud.storage_control_v2 import StorageControlClient\n\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\nbucket_name = os.environ.get('GCS_BUCKET_NAME', 'your-gcs-bucket-name')\n\nif project_id == 'your-gcp-project-id':\n    print(\"Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.\")\n    exit()\nif bucket_name == 'your-gcs-bucket-name':\n    print(\"Please set the GCS_BUCKET_NAME environment variable or replace 'your-gcs-bucket-name'.\")\n    exit()\n\nclient = StorageControlClient()\n\nparent_path = f\"projects/{project_id}/buckets/{bucket_name}\"\n\ntry:\n    # List managed folders in a bucket\n    print(f\"Listing managed folders in {parent_path}:\")\n    for managed_folder in client.list_managed_folders(parent=parent_path):\n        print(f\"- {managed_folder.name}\")\nexcept Exception as e:\n    print(f\"Error listing managed folders: {e}\")\n    print(\"Ensure you have appropriate IAM permissions (e.g., 'roles/storage.admin') for the bucket and that Application Default Credentials are configured.\")\n","lang":"python","description":"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`)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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`.","message":"Managed Folders are a new feature and require specific IAM permissions beyond standard bucket access. Incorrect or insufficient permissions can lead to `PermissionDenied` errors.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Resource paths for operations (e.g., `parent` for `list_managed_folders`) must follow a strict format like `projects/{project_id}/buckets/{bucket_name}`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}