Storage.buckets.lock Retention Policy

Locks retention policy on a bucket.

POST/b/{bucket}/lockRetentionPolicy

Use it in a workflow

Add a step and choose the Google Cloud Storage connector.
Pick the Storage.buckets.lock Retention Policy action (under buckets).
Fill in the fields below, then reference the result from later steps as {{storageBucketsLockRetentionPolicy.response.data}}.

Request

Path parameters

bucketstringrequired

Name of a bucket.

Query parameters

altstring

Data format for the response.

One ofjson

fieldsstring

Selector specifying which fields to include in a partial response.

keystring

API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.

oauth_tokenstring

OAuth 2.0 token for the current user.

prettyPrintboolean

Returns response with indentations and line breaks.

quotaUserstring

An opaque string that represents a user for quota purposes. Must not exceed 40 characters.

uploadTypestring

Upload protocol for media (e.g. "media", "multipart", "resumable").

userIpstring

Deprecated. Please use quotaUser instead.

ifMetagenerationMatchstringrequired

Makes the operation conditional on whether bucket's current metageneration matches the given value.

userProjectstring

The project to be billed for this request. Required for Requester Pays buckets.

Response

Returns 200 with an object. Read it in later steps with {{storageBucketsLockRetentionPolicy.response.data.<field>}}.

aclarray<object>

Access controls on the bucket.

bucketstring

The name of the bucket.

domainstring

The domain associated with the entity, if any.

emailstring

The email address associated with the entity, if any.

entitystring

The entity holding the permission, in one of the following forms: - user-userId - user-email - group-groupId - group-email - domain-domain - project-team-projectId - allUsers - allAuthenticatedUsers Examples: - The user liz@example.com would be user-liz@example.com. - The group example@googlegroups.com would be group-example@googlegroups.com. - To refer to all members of the Google Apps for Business domain example.com, the entity would be domain-example.com.

entityIdstring

The ID for the entity, if any.

etagstring

HTTP 1.1 Entity tag for the access-control entry.

idstring

The ID of the access-control entry.

kindstring

The kind of item this is. For bucket access control entries, this is always storage#bucketAccessControl.

Default "storage#bucketAccessControl"

projectTeamobject2 fields

The project team associated with the entity, if any.

rolestring

The access permission for the entity.

selfLinkstring

The link to this access-control entry.

autoclassobject

The bucket's Autoclass configuration.

enabledboolean

Whether or not Autoclass is enabled on this bucket

toggleTimestring (date-time)

A date and time in RFC 3339 format representing the instant at which "enabled" was last toggled.

billingobject

The bucket's billing configuration.

requesterPaysboolean

When set to true, Requester Pays is enabled for this bucket.

corsarray<object>

The bucket's Cross-Origin Resource Sharing (CORS) configuration.

maxAgeSecondsinteger (int32)

The value, in seconds, to return in the Access-Control-Max-Age header used in preflight responses.

methodarray<string>

The list of HTTP methods on which to include CORS response headers, (GET, OPTIONS, POST, etc) Note: "*" is permitted in the list of methods, and means "any method".

originarray<string>

The list of Origins eligible to receive CORS response headers. Note: "*" is permitted in the list of origins, and means "any Origin".

responseHeaderarray<string>

The list of HTTP headers other than the simple response headers to give permission for the user-agent to share across domains.

customPlacementConfigobject

The bucket's custom placement configuration for Custom Dual Regions.

dataLocationsarray<string>

The list of regional locations in which data is placed.

defaultEventBasedHoldboolean

The default value for event-based hold on newly created objects in this bucket. Event-based hold is a way to retain objects indefinitely until an event occurs, signified by the hold's release. After being released, such objects will be subject to bucket-level retention (if any). One sample use case of this flag is for banks to hold loan documents for at least 3 years after loan is paid in full. Here, bucket-level retention is 3 years and the event is loan being paid in full. In this example, these objects will be held intact for any number of years until the event has occurred (event-based hold on the object is released) and then 3 more years after that. That means retention duration of the objects begins from the moment event-based hold transitioned from true to false. Objects under event-based hold cannot be deleted, overwritten or archived until the hold is removed.

defaultObjectAclarray<object>

Default access controls to apply to new objects when no ACL is provided.

bucketstring

The name of the bucket.

domainstring

The domain associated with the entity, if any.

emailstring

The email address associated with the entity, if any.

entitystring

entityIdstring

The ID for the entity, if any.

etagstring

HTTP 1.1 Entity tag for the access-control entry.

generationstring (int64)

The content generation of the object, if applied to an object.

idstring

The ID of the access-control entry.

kindstring

The kind of item this is. For object access control entries, this is always storage#objectAccessControl.

Default "storage#objectAccessControl"

objectstring

The name of the object, if applied to an object.

projectTeamobject2 fields

The project team associated with the entity, if any.

rolestring

The access permission for the entity.

selfLinkstring

The link to this access-control entry.

encryptionobject

Encryption configuration for a bucket.

defaultKmsKeyNamestring

A Cloud KMS key that will be used to encrypt objects inserted into this bucket, if no encryption method is specified.

etagstring

HTTP 1.1 Entity tag for the bucket.

iamConfigurationobject

The bucket's IAM configuration.

bucketPolicyOnlyobject2 fields

The bucket's uniform bucket-level access configuration. The feature was formerly known as Bucket Policy Only. For backward compatibility, this field will be populated with identical information as the uniformBucketLevelAccess field. We recommend using the uniformBucketLevelAccess field to enable and disable the feature.

publicAccessPreventionstring

The bucket's Public Access Prevention configuration. Currently, 'inherited' and 'enforced' are supported.

uniformBucketLevelAccessobject2 fields

The bucket's uniform bucket-level access configuration.

idstring

The ID of the bucket. For buckets, the id and name properties are the same.

kindstring

The kind of item this is. For buckets, this is always storage#bucket.

Default "storage#bucket"

labelsobject

User-provided labels, in key/value pairs.

lifecycleobject

The bucket's lifecycle configuration. See lifecycle management for more information.

rulearray<object>2 fields

A lifecycle management rule, which is made of an action to take and the condition(s) under which the action will be taken.

locationstring

The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Defaults to US. See the developer's guide for the authoritative list.

locationTypestring

The type of the bucket location.

loggingobject

The bucket's logging configuration, which defines the destination bucket and optional name prefix for the current bucket's logs.

logBucketstring

The destination bucket where the current bucket's logs should be placed.

logObjectPrefixstring

A prefix for log object names.

metagenerationstring (int64)

The metadata generation of this bucket.

namestring

The name of the bucket.

ownerobject

The owner of the bucket. This is always the project team's owner group.

entitystring

The entity, in the form project-owner-projectId.

entityIdstring

The ID for the entity.

projectNumberstring (uint64)

The project number of the project the bucket belongs to.

retentionPolicyobject

The bucket's retention policy. The retention policy enforces a minimum retention time for all objects contained in the bucket, based on their creation time. Any attempt to overwrite or delete objects younger than the retention period will result in a PERMISSION_DENIED error. An unlocked retention policy can be modified or removed from the bucket via a storage.buckets.update operation. A locked retention policy cannot be removed or shortened in duration for the lifetime of the bucket. Attempting to remove or decrease period of a locked retention policy will result in a PERMISSION_DENIED error.

effectiveTimestring (date-time)

Server-determined value that indicates the time from which policy was enforced and effective. This value is in RFC 3339 format.

isLockedboolean

Once locked, an object retention policy cannot be modified.

retentionPeriodstring (int64)

The duration in seconds that objects need to be retained. Retention duration must be greater than zero and less than 100 years. Note that enforcement of retention periods less than a day is not guaranteed. Such periods should only be used for testing purposes.

rpostring

The Recovery Point Objective (RPO) of this bucket. Set to ASYNC_TURBO to turn on Turbo Replication on a bucket.

satisfiesPZSboolean

Reserved for future use.

selfLinkstring

The URI of this bucket.

storageClassstring

The bucket's default storage class, used whenever no storageClass is specified for a newly-created object. This defines how objects in the bucket are stored and determines the SLA and the cost of storage. Values include MULTI_REGIONAL, REGIONAL, STANDARD, NEARLINE, COLDLINE, ARCHIVE, and DURABLE_REDUCED_AVAILABILITY. If this value is not specified when the bucket is created, it will default to STANDARD. For more information, see storage classes.

timeCreatedstring (date-time)

The creation time of the bucket in RFC 3339 format.

updatedstring (date-time)

The modification time of the bucket in RFC 3339 format.

versioningobject

The bucket's versioning configuration.

enabledboolean

While set to true, versioning is fully enabled for this bucket.

websiteobject

The bucket's website configuration, controlling how the service behaves when accessing bucket contents as a web site. See the Static Website Examples for more information.

mainPageSuffixstring

If the requested object path is missing, the service will ensure the path has a trailing '/', append this suffix, and attempt to retrieve the resulting object. This allows the creation of index.html objects to represent directory pages.

notFoundPagestring

If the requested object path is missing, and any mainPageSuffix object is missing, if applicable, the service will return the named object from this bucket as the content for a 404 Not Found result.

json

{
  "acl": [
    {
      "bucket": "string",
      "domain": "string",
      "email": "string",
      "entity": "string",
      "entityId": "string",
      "etag": "string",
      "id": "string",
      "kind": "storage#bucketAccessControl",
      "projectTeam": {
        "projectNumber": "string",
        "team": "string"
      },
      "role": "string",
      "selfLink": "string"
    }
  ],
  "autoclass": {
    "enabled": false,
    "toggleTime": "2025-01-01T00:00:00Z"
  },
  "billing": {
    "requesterPays": false
  },
  "cors": [
    {
      "maxAgeSeconds": 0,
      "method": [
        "string"
      ],
      "origin": [
        "string"
      ],
      "responseHeader": [
        "string"
      ]
    }
  ],
  "customPlacementConfig": {
    "dataLocations": [
      "string"
    ]
  },
  "defaultEventBasedHold": false,
  "defaultObjectAcl": [
    {
      "bucket": "string",
      "domain": "string",
      "email": "string",
      "entity": "string",
      "entityId": "string",
      "etag": "string",
      "generation": "string",
      "id": "string",
      "kind": "storage#objectAccessControl",
      "object": "string",
      "projectTeam": {
        "projectNumber": "string",
        "team": "string"
      },
      "role": "string"
    }
  ],
  "encryption": {
    "defaultKmsKeyName": "string"
  },
  "etag": "string",
  "iamConfiguration": {
    "bucketPolicyOnly": {
      "enabled": false,
      "lockedTime": "2025-01-01T00:00:00Z"
    },
    "publicAccessPrevention": "string",
    "uniformBucketLevelAccess": {
      "enabled": false,
      "lockedTime": "2025-01-01T00:00:00Z"
    }
  },
  "id": "string",
  "kind": "storage#bucket"
}

Need more? See the Google Cloud Storage guide for connection setup and behaviour shared by every action.

Was this page helpful?