Package google.storage.v2

Index

Storage

API Overview and Naming Syntax

The Cloud Storage gRPC API allows applications to read and write data through the abstractions of buckets and objects. For a description of these abstractions please see Cloud Storage documentation.

Resources are named as follows:

  • Projects are referred to as they are defined by the Resource Manager API, using strings like projects/123456 or projects/my-string-id.
  • Buckets are named using string names of the form: projects/{project}/buckets/{bucket}. For globally unique buckets, _ may be substituted for the project.
  • Objects are uniquely identified by their name along with the name of the bucket they belong to, as separate strings in this API. For example:
ReadObjectRequest {
    bucket: 'projects/_/buckets/my-bucket'
    object: 'my-object'
    }

Note that object names can contain / characters, which are treated as any other character (no special directory semantics).

BidiReadObject

rpc BidiReadObject(BidiReadObjectRequest) returns (BidiReadObjectResponse)

Reads an object's data.

This bi-directional API reads data from an object, allowing you to request multiple data ranges within a single stream, even across several messages. If an error occurs with any request, the stream closes with a relevant error code. Since you can have multiple outstanding requests, the error response includes a BidiReadObjectRangesError field detailing the specific error for each pending read_id.

IAM Permissions:

Requires storage.objects.get IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
BidiWriteObject

rpc BidiWriteObject(BidiWriteObjectRequest) returns (BidiWriteObjectResponse)

Stores a new object and metadata.

This is similar to the WriteObject call with the added support for manual flushing of persisted state, and the ability to determine current persisted size without closing the stream.

The client may specify one or both of the state_lookup and flush fields in each BidiWriteObjectRequest. If flush is specified, the data written so far is persisted to storage. If state_lookup is specified, the service will respond with a BidiWriteObjectResponse that contains the persisted size. If both flush and state_lookup are specified, the flush will always occur before a state_lookup, so that both may be set in the same request and the returned state is the state of the object post-flush. When the stream is closed, a BidiWriteObjectResponse will always be sent to the client, regardless of the value of state_lookup.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
CancelResumableWrite

rpc CancelResumableWrite(CancelResumableWriteRequest) returns (CancelResumableWriteResponse)

Cancels an in-progress resumable upload.

Any attempts to write to the resumable upload after cancelling the upload fail.

The behavior for any in-progress write operations is not guaranteed; they could either complete before the cancellation or fail if the cancellation completes first.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
ComposeObject

rpc ComposeObject(ComposeObjectRequest) returns (Object)

Concatenates a list of existing objects into a new object in the same bucket. The existing source objects are unaffected by this operation.

For information about object composition, see Composite objects and for information about tool-specific guides to perform a composition, see Compose objects.

IAM Permissions:

Requires the storage.objects.create and storage.objects.get IAM permissions to use this method. If the new composite object overwrites an existing object, the authenticated user must also have the storage.objects.delete permission. If the request body includes the retention property, the authenticated user must also have the storage.objects.setRetention IAM permission.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
CreateBucket

rpc CreateBucket(CreateBucketRequest) returns (Bucket)

Creates a new bucket.

IAM Permissions:

Requires storage.buckets.create IAM permission on the bucket. Additionally, to enable specific bucket features, the authenticated user must have the following permissions:

  • To enable object retention using the enableObjectRetention query parameter: storage.buckets.enableObjectRetention
  • To set the bucket IP filtering rules: storage.buckets.setIpFilter
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
DeleteBucket

rpc DeleteBucket(DeleteBucketRequest) returns (Empty)

Permanently deletes an empty bucket. The request fails if there are any live or noncurrent objects in the bucket, but the request succeeds if the bucket only contains soft-deleted objects or incomplete uploads, such as ongoing XML API multipart uploads. Does not permanently delete soft-deleted objects.

When this API is used to delete a bucket containing an object that has a soft delete policy enabled, the object becomes soft deleted, and the softDeleteTime and hardDeleteTime properties are set on the object.

Objects and multipart uploads that were in the bucket at the time of deletion are also retained for the specified retention duration. When a soft-deleted bucket reaches the end of its retention duration, it is permanently deleted. The hardDeleteTime of the bucket always equals or exceeds the expiration time of the last soft-deleted object in the bucket.

IAM Permissions:

Requires storage.buckets.delete IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
DeleteObject

rpc DeleteObject(DeleteObjectRequest) returns (Empty)

Deletes an object and its metadata. Deletions are permanent if versioning is not enabled for the bucket, or if the generation parameter is used, or if soft delete is not enabled for the bucket. When this API is used to delete an object from a bucket that has soft delete policy enabled, the object becomes soft deleted, and the softDeleteTime and hardDeleteTime properties are set on the object. This API cannot be used to permanently delete soft-deleted objects. Soft-deleted objects are permanently deleted according to their hardDeleteTime.

You can use the RestoreObject API to restore soft-deleted objects until the soft delete retention period has passed.

IAM Permissions:

Requires storage.objects.delete IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
GetBucket

rpc GetBucket(GetBucketRequest) returns (Bucket)

Returns metadata for the specified bucket.

IAM Permissions:

Requires storage.buckets.get IAM permission on the bucket. Additionally, to return specific bucket metadata, the authenticated user must have the following permissions:

  • To return the IAM policies: storage.buckets.getIamPolicy
  • To return the bucket IP filtering rules: storage.buckets.getIpFilter
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
GetIamPolicy

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

Gets the IAM policy for a specified bucket or managed folder. The resource field in the request should be projects/_/buckets/{bucket} for a bucket, or projects/_/buckets/{bucket}/managedFolders/{managedFolder} for a managed folder.

IAM Permissions:

Requires storage.buckets.getIamPolicy on the bucket or storage.managedFolders.getIamPolicy IAM permission on the managed folder.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
GetObject

rpc GetObject(GetObjectRequest) returns (Object)

Retrieves object metadata.

IAM Permissions:

Requires storage.objects.get IAM permission on the bucket. To return object ACLs, the authenticated user must also have the storage.objects.getIamPolicy permission.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
ListBuckets

rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse)

Retrieves a list of buckets for a given project, ordered lexicographically by name.

IAM Permissions:

Requires storage.buckets.list IAM permission on the bucket. Additionally, to enable specific bucket features, the authenticated user must have the following permissions:

  • To list the IAM policies: storage.buckets.getIamPolicy
  • To list the bucket IP filtering rules: storage.buckets.getIpFilter
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
ListObjects

rpc ListObjects(ListObjectsRequest) returns (ListObjectsResponse)

Retrieves a list of objects matching the criteria.

IAM Permissions:

The authenticated user requires storage.objects.list IAM permission to use this method. To return object ACLs, the authenticated user must also have the storage.objects.getIamPolicy permission.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
LockBucketRetentionPolicy

rpc LockBucketRetentionPolicy(LockBucketRetentionPolicyRequest) returns (Bucket)

Permanently locks the retention policy that is currently applied to the specified bucket. Caution: Locking a bucket is an irreversible action. Once you lock a bucket:

  • You cannot remove the retention policy from the bucket.
  • You cannot decrease the retention period for the policy.

Once locked, you must delete the entire bucket in order to remove the bucket's retention policy. However, before you can delete the bucket, you must delete all the objects in the bucket, which is only possible if all the objects have reached the retention period set by the retention policy.

IAM Permissions:

Requires storage.buckets.update IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
MoveObject

rpc MoveObject(MoveObjectRequest) returns (Object)

Moves the source object to the destination object in the same bucket. This operation moves a source object to a destination object in the same bucket by renaming the object. The move itself is an atomic transaction, ensuring all steps either complete successfully or no changes are made.

IAM Permissions:

Requires the following IAM permissions to use this method:

  • storage.objects.move
  • storage.objects.create
  • storage.objects.delete (only required if overwriting an existing object)
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
QueryWriteStatus

rpc QueryWriteStatus(QueryWriteStatusRequest) returns (QueryWriteStatusResponse)

Determines the persisted_size of an object that is being written. This method is part of the resumable upload feature. The returned value is the size of the object that has been persisted so far. The value can be used as the write_offset for the next Write() call.

If the object does not exist, meaning if it was deleted, or the first Write() has not yet reached the service, this method returns the error NOT_FOUND.

This method is useful for clients that buffer data and need to know which data can be safely evicted. The client can call QueryWriteStatus() at any time to determine how much data has been logged for this object. For any sequence of QueryWriteStatus() calls for a given object name, the sequence of returned persisted_size values are non-decreasing.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
ReadObject

rpc ReadObject(ReadObjectRequest) returns (ReadObjectResponse)

Retrieves object data.

IAM Permissions:

Requires storage.objects.get IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
RestoreObject

rpc RestoreObject(RestoreObjectRequest) returns (Object)

Restores a soft-deleted object. When a soft-deleted object is restored, a new copy of that object is created in the same bucket and inherits the same metadata as the soft-deleted object. The inherited metadata is the metadata that existed when the original object became soft deleted, with the following exceptions:

  • The createTime of the new object is set to the time at which the soft-deleted object was restored.
  • The softDeleteTime and hardDeleteTime values are cleared.
  • A new generation is assigned and the metageneration is reset to 1.
  • If the soft-deleted object was in a bucket that had Autoclass enabled, the new object is restored to Standard storage.
  • The restored object inherits the bucket's default object ACL, unless copySourceAcl is true.

If a live object using the same name already exists in the bucket and becomes overwritten, the live object becomes a noncurrent object if Object Versioning is enabled on the bucket. If Object Versioning is not enabled, the live object becomes soft deleted.

IAM Permissions:

Requires the following IAM permissions to use this method:

  • storage.objects.restore
  • storage.objects.create
  • storage.objects.delete (only required if overwriting an existing object)
  • storage.objects.getIamPolicy (only required if projection is full and the relevant bucket has uniform bucket-level access disabled)
  • storage.objects.setIamPolicy (only required if copySourceAcl is true and the relevant bucket has uniform bucket-level access disabled)
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
RewriteObject

rpc RewriteObject(RewriteObjectRequest) returns (RewriteResponse)

Rewrites a source object to a destination object. Optionally overrides metadata.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
SetIamPolicy

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

Updates an IAM policy for the specified bucket or managed folder. The resource field in the request should be projects/_/buckets/{bucket} for a bucket, or projects/_/buckets/{bucket}/managedFolders/{managedFolder} for a managed folder.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
StartResumableWrite

rpc StartResumableWrite(StartResumableWriteRequest) returns (StartResumableWriteResponse)

Starts a resumable write operation. This method is part of the Resumable upload feature. This allows you to upload large objects in multiple chunks, which is more resilient to network interruptions than a single upload. The validity duration of the write operation, and the consequences of it becoming invalid, are service-dependent.

IAM Permissions:

Requires storage.objects.create IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

Tests a set of permissions on the given bucket, object, or managed folder to see which, if any, are held by the caller. The resource field in the request should be projects/_/buckets/{bucket} for a bucket, projects/_/buckets/{bucket}/objects/{object} for an object, or projects/_/buckets/{bucket}/managedFolders/{managedFolder} for a managed folder.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
UpdateBucket

rpc UpdateBucket(UpdateBucketRequest) returns (Bucket)

Updates a bucket. Changes to the bucket are readable immediately after writing, but configuration changes may take time to propagate. This method supports patch semantics.

IAM Permissions:

Requires storage.buckets.update IAM permission on the bucket. Additionally, to enable specific bucket features, the authenticated user must have the following permissions:

  • To set bucket IP filtering rules: storage.buckets.setIpFilter
  • To update public access prevention policies or access control lists (ACLs): storage.buckets.setIamPolicy
Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
UpdateObject

rpc UpdateObject(UpdateObjectRequest) returns (Object)

Updates an object's metadata. Equivalent to JSON API's storage.objects.patch.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.
WriteObject

rpc WriteObject(WriteObjectRequest) returns (WriteObjectResponse)

Stores a new object and metadata.

An object can be written either in a single message stream or in a resumable sequence of message streams. To write using a single stream, the client should include in the first message of the stream an WriteObjectSpec describing the destination bucket, object, and any preconditions. Additionally, the final message must set 'finish_write' to true, or else it is an error.

For a resumable write, the client should instead call StartResumableWrite(), populating a WriteObjectSpec into that request. They should then attach the returned upload_id to the first message of each following call to WriteObject. If the stream is closed before finishing the upload (either explicitly by the client or due to a network error or an error response from the server), the client should do as follows:

  • Check the result Status of the stream, to determine if writing can be resumed on this stream or must be restarted from scratch (by calling StartResumableWrite()). The resumable errors are DEADLINE_EXCEEDED, INTERNAL, and UNAVAILABLE. For each case, the client should use binary exponential backoff before retrying. Additionally, writes can be resumed after RESOURCE_EXHAUSTED errors, but only after taking appropriate measures, which may include reducing aggregate send rate across clients and/or requesting a quota increase for your project.
  • If the call to WriteObject returns ABORTED, that indicates concurrent attempts to update the resumable write, caused either by multiple racing clients or by a single client where the previous request was timed out on the client side but nonetheless reached the server. In this case the client should take steps to prevent further concurrent writes. For example, increase the timeouts and stop using more than one process to perform the upload. Follow the steps below for resuming the upload.
  • For resumable errors, the client should call QueryWriteStatus() and then continue writing from the returned persisted_size. This may be less than the amount of data the client previously sent. Note also that it is acceptable to send data starting at an offset earlier than the returned persisted_size; in this case, the service skips data at offsets that were already persisted (without checking that it matches the previously written data), and write only the data starting from the persisted offset. Even though the data isn't written, it may still incur a performance cost over resuming at the correct write offset. This behavior can make client-side handling simpler in some cases.
  • Clients must only send data that is a multiple of 256 KiB per message, unless the object is being finished with finish_write set to true.

The service does not view the object as complete until the client has sent a WriteObjectRequest with finish_write set to true. Sending any requests on a stream after sending a request with finish_write set to true causes an error. The client must check the response it receives to determine how much data the service is able to commit and whether the service views the object as complete.

Attempting to resume an already finalized object results in an OK status, with a WriteObjectResponse containing the finalized object's metadata.

Alternatively, you can use the BidiWriteObject operation to write an object with controls over flushing and the ability to fetch the ability to determine the current persisted size.

IAM Permissions:

Requires storage.objects.create IAM permission on the bucket.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/devstorage.full_control
  • https://www.googleapis.com/auth/devstorage.read_only
  • https://www.googleapis.com/auth/devstorage.read_write
  • https://www.googleapis.com/auth/devstorage.write_only
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/cloud-platform.read-only

For more information, see the Authentication Overview.

AppendObjectSpec

Describes an attempt to append to an object, possibly over multiple requests.

Fields
bucket

string

Required. The name of the bucket containing the object to write.
object

string

Required. The name of the object to open for writing.
generation

int64

Required. The generation number of the object to open for writing.
if_metageneration_match

int64

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

Note that metageneration preconditions are only checked if write_handle is empty.
if_metageneration_not_match

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.

Note that metageneration preconditions are only checked if write_handle is empty.
routing_token

string

An optional routing token that influences request routing for the stream. Must be provided if a BidiWriteObjectRedirectedError is returned.
write_handle

BidiWriteHandle

An optional write handle returned from a previous BidiWriteObjectResponse message or a BidiWriteObjectRedirectedError error.

Note that metageneration preconditions are only checked if write_handle is empty.

BidiReadHandle

BidiReadHandle contains a handle from a previous BiDiReadObject invocation. The client can use this instead of BidiReadObjectSpec as an optimized way of opening subsequent bidirectional streams to the same object.

Fields
handle

bytes

Required. Opaque value describing a previous read.

BidiReadObjectError

Error extension proto containing details for all outstanding reads on the failed stream

Fields
read_range_errors[]

ReadRangeError

The error code for each outstanding read_range

BidiReadObjectRedirectedError

Error proto containing details for a redirected read. This error may be attached as details for an ABORTED response to BidiReadObject.

Fields
read_handle

BidiReadHandle

The read handle for the redirected read. If set, the client may use this in the BidiReadObjectSpec when retrying the read stream.
routing_token

string

The routing token the client must use when retrying the read stream. This value must be provided in the header x-goog-request-params, with key routing_token and this string verbatim as the value.

BidiReadObjectRequest

Request message for BidiReadObject.

Fields
read_object_spec

BidiReadObjectSpec

Optional. The first message of each stream should set this field. If this is not the first message, an error is returned. Describes the object to read.
read_ranges[]

ReadRange

Optional. Provides a list of 0 or more (up to 100) ranges to read. If a single range is large enough to require multiple responses, they are guaranteed to be delivered in increasing offset order. There are no ordering guarantees across ranges. When no ranges are provided, the response message will not include ObjectRangeData. For full object downloads, the offset and size can be set to 0.

BidiReadObjectResponse

Response message for BidiReadObject.

Fields
object_data_ranges[]

ObjectRangeData

A portion of the object's data. The service may leave data empty for any given ReadResponse. This enables the service to inform the client that the request is still live while it is running an operation to generate more data. The service may pipeline multiple responses belonging to different read requests. Each ObjectRangeData entry will have a read_id set to the same value as the corresponding source read request.
metadata

Object

Metadata of the object whose media is being returned. Only populated in the first response in the stream and not populated when the stream is opened with a read handle.
read_handle

BidiReadHandle

This field is periodically refreshed, however it may not be set in every response. It allows the client to more efficiently open subsequent bidirectional streams to the same object.

BidiReadObjectSpec

Describes the object to read in a BidiReadObject request.

Fields
bucket

string

Required. The name of the bucket containing the object to read.
object

string

Required. The name of the object to read.
generation

int64

Optional. If present, selects a specific revision of this object (as opposed to the latest version, the default).
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.
read_mask
(deprecated)

FieldMask

Mask specifying which fields to read. The checksummed_data field and its children will always be present. If no mask is specified, will default to all fields except metadata.owner and metadata.acl. * may be used to mean "all fields". As per https://google.aip.dev/161, this field is deprecated. As an alternative, grpc metadata can be used: https://cloud.google.com/apis/docs/system-parameters#definitions
read_handle

BidiReadHandle

The client can optionally set this field. The read handle is an optimized way of creating new streams. Read handles are generated and periodically refreshed from prior reads.
routing_token

string

The routing token that influences request routing for the stream. Must be provided if a BidiReadObjectRedirectedError is returned.

BidiWriteHandle

BidiWriteHandle contains a handle from a previous BidiWriteObject invocation. The client can use this as an optimized way of opening subsequent bidirectional streams to the same object.

Fields
handle

bytes

Required. Opaque value describing a previous write.

BidiWriteObjectRedirectedError

Error proto containing details for a redirected write. This error may be attached as details for an ABORTED response to BidiWriteObject.

Fields
routing_token

string

The routing token the client must use when retrying the write stream. This value must be provided in the header x-goog-request-params, with key routing_token and this string verbatim as the value.
write_handle

BidiWriteHandle

Opaque value describing a previous write. If set, the client must use this in an AppendObjectSpec first_message when retrying the write stream. If not set, clients may retry the original request.
generation

int64

The generation of the object that triggered the redirect. This is set iff write_handle is set. If set, the client must use this in an AppendObjectSpec first_message when retrying the write stream.

BidiWriteObjectRequest

Request message for BidiWriteObject.

Fields
write_offset

int64

Required. The offset from the beginning of the object at which the data should be written.

In the first WriteObjectRequest of a WriteObject() action, it indicates the initial offset for the Write() call. The value must be equal to the persisted_size that a call to QueryWriteStatus() would return (0 if this is the first write to the object).

On subsequent calls, this value must be no larger than the sum of the first write_offset and the sizes of all data chunks sent previously on this stream.

An invalid value will cause an error.
object_checksums

ObjectChecksums

Optional. Checksums for the complete object. If the checksums computed by the service don't match the specified checksums the call will fail. May only be provided in the first request or the last request (with finish_write set).
state_lookup

bool

Optional. For each BidiWriteObjectRequest where state_lookup is true or the client closes the stream, the service sends a BidiWriteObjectResponse containing the current persisted size. The persisted size sent in responses covers all the bytes the server has persisted thus far and can be used to decide what data is safe for the client to drop. Note that the object's current size reported by the BidiWriteObjectResponse may lag behind the number of bytes written by the client. This field is ignored if finish_write is set to true.
flush

bool

Optional. Persists data written on the stream, up to and including the current message, to permanent storage. This option should be used sparingly as it may reduce performance. Ongoing writes will periodically be persisted on the server even when flush is not set. This field is ignored if finish_write is set to true since there's no need to checkpoint or flush if this message completes the write.
finish_write

bool

Optional. If true, this indicates that the write is complete. Sending any WriteObjectRequests subsequent to one in which finish_write is true will cause an error. For a non-resumable write (where the upload_id was not set in the first message), it is an error not to set this field in the final message of the stream.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
Union field first_message. The first message of each stream should set one of the following. first_message can be only one of the following:
upload_id

string

For resumable uploads. This should be the upload_id returned from a call to StartResumableWriteResponse.
write_object_spec

WriteObjectSpec

For non-resumable uploads. Describes the overall upload, including the destination bucket and object name, preconditions, etc.
append_object_spec

AppendObjectSpec

For appendable uploads. Describes the object to append to.
Union field data. A portion of the data for the object. data can be only one of the following:
checksummed_data

ChecksummedData

The data to insert. If a crc32c checksum is provided that doesn't match the checksum computed by the service, the request will fail.

BidiWriteObjectResponse

Response message for BidiWriteObject.

Fields
Union field write_status. The response will set one of the following. write_status can be only one of the following:
persisted_size

int64

The total number of bytes that have been processed for the given object from all WriteObject calls. Only set if the upload has not finalized.
resource

Object

A resource containing the metadata for the uploaded object. Only set if the upload has finalized.
write_handle

BidiWriteHandle

An optional write handle that will periodically be present in response messages. Clients should save it for later use in establishing a new stream if a connection is interrupted.

Bucket

A bucket.

Fields
name

string

Identifier. The name of the bucket. Format: projects/{project}/buckets/{bucket}
bucket_id

string

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

string

The etag of the bucket. If included in the metadata of an update bucket request, the operation will only be performed if the etag matches that of the bucket.
project

string

Immutable. The project which owns this bucket, in the format of projects/{projectIdentifier}. {projectIdentifier} can be the project ID or project number. Output values will always be in project number format.
metageneration

int64

Output only. The metadata generation of this bucket.
location

string

Immutable. The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Defaults to US. Attempting to update this field after the bucket is created results in an error.
location_type

string

Output only. The location type of the bucket (region, dual-region, multi-region, etc).
storage_class

string

Optional. 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. If this value is not specified when the bucket is created, it will default to STANDARD. For more information, see Storage classes.
rpo

string

Optional. The recovery point objective for cross-region replication of the bucket. Applicable only for dual- and multi-region buckets. DEFAULT uses default replication. ASYNC_TURBO enables turbo replication, valid for dual-region buckets only. If rpo is not specified when the bucket is created, it defaults to DEFAULT. For more information, see Turbo replication.
acl[]

BucketAccessControl

Optional. Access controls on the bucket. If iam_config.uniform_bucket_level_access is enabled on this bucket, requests to set, read, or modify acl is an error.
default_object_acl[]

ObjectAccessControl

Optional. Default access controls to apply to new objects when no ACL is provided. If iam_config.uniform_bucket_level_access is enabled on this bucket, requests to set, read, or modify acl is an error.
lifecycle

Lifecycle

Optional. The bucket's lifecycle configuration. For more information, see Object Lifecycle Management.
create_time

Timestamp

Output only. The creation time of the bucket.
cors[]

Cors

Optional. The bucket's CORS configuration.
update_time

Timestamp

Output only. The modification time of the bucket.
default_event_based_hold

bool

Optional. 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 are 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 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.
labels

map<string, string>

Optional. User-provided labels, in key/value pairs.
website

Website

Optional. The bucket's website config, controlling how the service behaves when accessing bucket contents as a web site. For details, see Static website examples.
versioning

Versioning

Optional. The bucket's versioning config.
logging

Logging

Optional. The bucket's logging config, which defines the destination bucket and name prefix (if any) for the current bucket's logs.
owner

Owner

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

Encryption

Optional. Encryption config for a bucket.
billing

Billing

Optional. The bucket's billing config.
retention_policy

RetentionPolicy

Optional. 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 results in a PERMISSION_DENIED error.
iam_config

IamConfig

Optional. The bucket's IAM config.
satisfies_pzs

bool

Optional. Reserved for future use.
custom_placement_config

CustomPlacementConfig

Optional. Configuration that, if present, specifies the data placement for a configurable dual-region.
autoclass

Autoclass

Optional. The bucket's Autoclass configuration. If there is no configuration, the Autoclass feature is disabled and has no effect on the bucket.
hierarchical_namespace

HierarchicalNamespace

Optional. The bucket's hierarchical namespace configuration. If there is no configuration, the hierarchical namespace feature is disabled and have no effect on the bucket.
soft_delete_policy

SoftDeletePolicy

Optional. The bucket's soft delete policy. The soft delete policy prevents soft-deleted objects from being permanently deleted.
object_retention

ObjectRetention

Optional. The bucket's object retention configuration. Must be enabled before objects in the bucket may have retention configured.
ip_filter

IpFilter

Optional. The bucket's IP filter configuration.

Autoclass

Configuration for a bucket's Autoclass feature.

Fields
enabled

bool

Optional. Enables Autoclass.
toggle_time

Timestamp

Output only. Latest instant at which the enabled field was set to true after being disabled/unconfigured or set to false after being enabled. If Autoclass is enabled when the bucket is created, the value of the toggle_time field is set to the bucket creation time.
terminal_storage_class

string

An object in an Autoclass bucket will eventually cool down to the terminal storage class if there is no access to the object. The only valid values are NEARLINE and ARCHIVE.
terminal_storage_class_update_time

Timestamp

Output only. Latest instant at which the autoclass terminal storage class was updated.

Billing

Billing properties of a bucket.

Fields
requester_pays

bool

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

Cors

Cross-Origin Response sharing (CORS) properties for a bucket. For details, see Cross-origin response. For more details about CORS in general, see Web Origin Concept.

Fields
origin[]

string

Optional. The list of origins eligible to receive CORS response headers. For more information about origins, see RFC 6454. Note: "*" is permitted in the list of origins, and means "any origin".
method[]

string

Optional. 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".
response_header[]

string

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

int32

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

CustomPlacementConfig

Configuration for configurable dual- regions. It should specify precisely two eligible regions within the same multi-region. For details, see locations.

Fields
data_locations[]

string

Optional. List of locations to use for data placement.

Encryption

Encryption properties of a bucket.

Fields
default_kms_key

string

Optional. The name of the Cloud KMS key that is used to encrypt objects inserted into this bucket, if no encryption method is specified.
google_managed_encryption_enforcement_config

GoogleManagedEncryptionEnforcementConfig

Optional. If omitted, then new objects with GMEK encryption-type is allowed. If set, then new objects created in this bucket must comply with enforcement config. Changing this has no effect on existing objects; it applies to new objects only.
customer_managed_encryption_enforcement_config

CustomerManagedEncryptionEnforcementConfig

Optional. If omitted, then new objects with CMEK encryption-type is allowed. If set, then new objects created in this bucket must comply with enforcement config. Changing this has no effect on existing objects; it applies to new objects only.
customer_supplied_encryption_enforcement_config

CustomerSuppliedEncryptionEnforcementConfig

Optional. If omitted, then new objects with CSEK encryption-type is allowed. If set, then new objects created in this bucket must comply with enforcement config. Changing this has no effect on existing objects; it applies to new objects only.

CustomerManagedEncryptionEnforcementConfig

Customer Managed Encryption (CMEK) enforcement config of a bucket.

Fields
restricted

bool

Whether Customer Managed Encryption (CMEK) is restricted for new objects within the bucket. If true, new objects can't be created using CMEK encryption. If false or unset, creation of new objects with CMEK encryption is allowed.
effective_time

Timestamp

Time from which the config was effective. This is service-provided.

CustomerSuppliedEncryptionEnforcementConfig

Customer Supplied Encryption (CSEK) enforcement config of a bucket.

Fields
restricted

bool

Whether Customer Supplied Encryption (CSEK) is restricted for new objects within the bucket. If true, new objects can't be created using CSEK encryption. If false or unset, creation of new objects with CSEK encryption is allowed.
effective_time

Timestamp

Time from which the config was effective. This is service-provided.

GoogleManagedEncryptionEnforcementConfig

Google Managed Encryption (GMEK) enforcement config of a bucket.

Fields
restricted

bool

Whether Google Managed Encryption (GMEK) is restricted for new objects within the bucket. If true, new objects can't be created using GMEK encryption. If false or unset, creation of new objects with GMEK encryption is allowed.
effective_time

Timestamp

Time from which the config was effective. This is service-provided.

HierarchicalNamespace

Configuration for a bucket's hierarchical namespace feature.

Fields
enabled

bool

Optional. Enables the hierarchical namespace feature.

IamConfig

Bucket restriction options.

Fields
uniform_bucket_level_access

UniformBucketLevelAccess

Optional. Bucket restriction options currently enforced on the bucket.
public_access_prevention

string

Optional. Whether IAM will enforce public access prevention. Valid values are enforced or inherited.

UniformBucketLevelAccess

Settings for Uniform Bucket level access. For more information, see Uniform bucket level access.

Fields
enabled

bool

Optional. If set, access checks only use bucket-level IAM policies or above.
lock_time

Timestamp

Optional. The deadline time for changing iam_config.uniform_bucket_level_access.enabled from true to false. Mutable until the specified deadline is reached, but not afterward.

IpFilter

The bucket IP filtering configuration. Specifies the network sources that can access the bucket, as well as its underlying objects.

Fields
vpc_network_sources[]

VpcNetworkSource

Optional. The list of network sources that are allowed to access operations on the bucket or the underlying objects.
allow_cross_org_vpcs

bool

Optional. Whether to allow VPC networks that are defined in vpcNetworkSource to originate from a different organization. If set to true, the request allows cross-organizational VPC networks. If set to false, the request restricts the VPC networks to the same organization as the bucket. If not specified, the default value is false.
mode

string

The state of the IP filter configuration. Valid values are Enabled and Disabled. When set to Enabled, IP filtering rules are applied to a bucket and all incoming requests to the bucket are evaluated against these rules. When set to Disabled, IP filtering rules are not applied to a bucket.
public_network_source

PublicNetworkSource

Public IP address ranges that are allowed to operate or access the bucket.
allow_all_service_agent_access

bool

Whether or not to allow service agent access to the bucket, regardless of the IP filter configuration. If the value is true, other Google Cloud services can use service agents to access the bucket without IP-based validation.

PublicNetworkSource

The public network IP address ranges that can access the bucket and its data.

Fields
allowed_ip_cidr_ranges[]

string

Optional. The list of IPv4 and IPv6 cidr blocks that are allowed to operate or access the bucket and its underlying objects.

VpcNetworkSource

The list of VPC networks that can access the bucket.

Fields
allowed_ip_cidr_ranges[]

string

Optional. The list of public or private IPv4 and IPv6 CIDR ranges that can access the bucket. In the CIDR IP address block, the specified IP address must be properly truncated, meaning all the host bits must be zero or else the input is considered malformed. For example, 192.0.2.0/24 is accepted but 192.0.2.1/24 is not. Similarly, for IPv6, 2001:db8::/32 is accepted whereas 2001:db8::1/32 is not.
network

string

Name of the network.

Format: projects/PROJECT_ID/global/networks/NETWORK_NAME

Lifecycle

Lifecycle properties of a bucket. For more information, see Object Lifecycle Management.

Fields
rule[]

Rule

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

Rule

A lifecycle rule, combining an action to take on an object and a condition which will trigger that action.

Fields
action

Action

Optional. The action to take.
condition

Condition

Optional. The condition under which the action is taken.

Action

An action to take on an object.

Fields
type

string

Optional. Type of the action. Currently, only Delete, SetStorageClass, and AbortIncompleteMultipartUpload are supported.
storage_class

string

Optional. Target storage class. Required iff the type of the action is SetStorageClass.

Condition

A condition of an object which triggers some action.

Fields
created_before

Date

Optional. This condition is satisfied when an object is created before midnight of the specified date in UTC.
matches_storage_class[]

string

Optional. Objects having any of the storage classes specified by this condition are matched. Values include MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, STANDARD, and DURABLE_REDUCED_AVAILABILITY.
custom_time_before

Date

Optional. An object matches this condition if the custom timestamp set on the object is before the specified date in UTC.
noncurrent_time_before

Date

Optional. This condition is relevant only for versioned objects. An object version satisfies this condition only if it became noncurrent before the specified date in UTC.
matches_prefix[]

string

Optional. List of object name prefixes. If any prefix exactly matches the beginning of the object name, the condition evaluates to true.
matches_suffix[]

string

Optional. List of object name suffixes. If any suffix exactly matches the end of the object name, the condition evaluates to true.
age_days

int32

Age of an object (in days). This condition is satisfied when an object reaches the specified age. A value of 0 indicates that all objects immediately match this condition.
is_live

bool

Relevant only for versioned objects. If the value is true, this condition matches live objects; if the value is false, it matches archived objects.
num_newer_versions

int32

Relevant only for versioned objects. If the value is N, this condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
days_since_custom_time

int32

Number of days that have elapsed since the custom timestamp set on an object. The value of the field must be a nonnegative integer.
days_since_noncurrent_time

int32

This condition is relevant only for versioned objects. An object version satisfies this condition only if these many days have been passed since it became noncurrent. The value of the field must be a nonnegative integer. If it's zero, the object version becomes eligible for Lifecycle action as soon as it becomes noncurrent.

Logging

Logging-related properties of a bucket.

Fields
log_bucket

string

Optional. The destination bucket where the current bucket's logs should be placed, using path format such as projects/123456/buckets/foo.
log_object_prefix

string

Optional. A prefix for log object names.

ObjectRetention

Object Retention related properties of a bucket.

Fields
enabled

bool

Optional. Output only. If true, object retention is enabled for the bucket.

RetentionPolicy

Retention policy properties of a bucket.

Fields
effective_time

Timestamp

Optional. Server-determined value that indicates the time from which policy was enforced and effective.
is_locked

bool

Optional. Once locked, an object retention policy cannot be modified.
retention_duration

Duration

Optional. The duration 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. Any nanos value specified are rounded down to the nearest second.

SoftDeletePolicy

Soft delete policy properties of a bucket.

Fields
retention_duration

Duration

The period of time that soft-deleted objects in the bucket must be retained and cannot be permanently deleted. The duration must be greater than or equal to 7 days and less than 1 year.
effective_time

Timestamp

Time from which the policy was effective. This is service-provided.

Versioning

Properties of a bucket related to versioning. For more information about Cloud Storage versioning, see Object versioning.

Fields
enabled

bool

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

Website

Properties of a bucket related to accessing the contents as a static website. For details, see hosting a static website using Cloud Storage.

Fields
main_page_suffix

string

Optional. 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.
not_found_page

string

Optional. 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.

BucketAccessControl

An access-control entry.

Fields
role

string

Optional. The access permission for the entity.
id

string

Optional. The ID of the access-control entry.
entity

string

Optional. The entity holding the permission, in one of the following forms: * user-{userid} * user-{email} * group-{groupid} * group-{email} * domain-{domain} * project-{team}-{projectnumber} * 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 * All members of the Google Apps for Business domain example.com would be domain-example.com For project entities, project-{team}-{projectnumber} format is returned on response.
entity_alt

string

Output only. The alternative entity format, if exists. For project entities, project-{team}-{projectid} format is returned on response.
entity_id

string

Optional. The ID for the entity, if any.
etag

string

Optional. The etag of the BucketAccessControl. If included in the metadata of an update or delete request message, the operation operation will only be performed if the etag matches that of the bucket's BucketAccessControl.
email

string

Optional. The email address associated with the entity, if any.
domain

string

Optional. The domain associated with the entity, if any.
project_team

ProjectTeam

Optional. The project team associated with the entity, if any.

CancelResumableWriteRequest

Request message for CancelResumableWrite.

Fields
upload_id

string

Required. The upload_id of the resumable upload to cancel. This should be copied from the upload_id field of StartResumableWriteResponse.

CancelResumableWriteResponse

This type has no fields.

Empty response message for canceling an in-progress resumable upload, is extended as needed.

ChecksummedData

Message used to convey content being read or written, along with an optional checksum.

Fields
content

bytes

Optional. The data.
crc32c

fixed32

If set, the CRC32C digest of the content field.

CommonObjectRequestParams

Parameters that can be passed to any object request.

Fields
encryption_algorithm

string

Optional. Encryption algorithm used with the Customer-Supplied Encryption Keys feature.
encryption_key_bytes

bytes

Optional. Encryption key used with the Customer-Supplied Encryption Keys feature. In raw bytes format (not base64-encoded).
encryption_key_sha256_bytes

bytes

Optional. SHA256 hash of encryption key used with the Customer-supplied encryption keys feature.

ComposeObjectRequest

Request message for ComposeObject.

Fields
destination

Object

Required. Properties of the resulting object.
source_objects[]

SourceObject

Optional. The list of source objects that is concatenated into a single object.
destination_predefined_acl

string

Optional. Apply a predefined set of access controls to the destination object. Valid values are "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
kms_key

string

Optional. Resource name of the Cloud KMS key, of the form projects/my-project/locations/my-location/keyRings/my-kr/cryptoKeys/my-key, that is used to encrypt the object. Overrides the object metadata's kms_key_name value, if any.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
object_checksums

ObjectChecksums

Optional. The checksums of the complete object. This is validated against the combined checksums of the component objects.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_metageneration_match

int64

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

SourceObject

Description of a source object for a composition request.

Fields
name

string

Required. The source object's name. All source objects must reside in the same bucket.
generation

int64

Optional. The generation of this object to use as the source.
object_preconditions

ObjectPreconditions

Optional. Conditions that must be met for this operation to execute.

ObjectPreconditions

Preconditions for a source object of a composition request.

Fields
if_generation_match

int64

Only perform the composition if the generation of the source object that would be used matches this value. If this value and a generation are both specified, they must be the same value or the call will fail.

ContentRange

Specifies a requested range of bytes to download.

Fields
start

int64

The starting offset of the object data. This value is inclusive.
end

int64

The ending offset of the object data. This value is exclusive.
complete_length

int64

The complete length of the object data.

CreateBucketRequest

Request message for CreateBucket.

Fields
parent

string

Required. The project to which this bucket belongs. This field must either be empty or projects/_. The project ID that owns this bucket should be specified in the bucket.project field.
bucket

Bucket

Optional. Properties of the new bucket being inserted. The name of the bucket is specified in the bucket_id field. Populating bucket.name field results in an error. The project of the bucket must be specified in the bucket.project field. This field must be in projects/{projectIdentifier} format, {projectIdentifier} can be the project ID or project number. The parent field must be either empty or projects/_.
bucket_id

string

Required. The ID to use for this bucket, which becomes the final component of the bucket's resource name. For example, the value foo might result in a bucket with the name projects/123456/buckets/foo.
predefined_acl

string

Optional. Apply a predefined set of access controls to this bucket. Valid values are "authenticatedRead", "private", "projectPrivate", "publicRead", or "publicReadWrite".
predefined_default_object_acl

string

Optional. Apply a predefined set of default object access controls to this bucket. Valid values are "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
enable_object_retention

bool

Optional. If true, enable object retention on the bucket.

CustomerEncryption

Describes the Customer-Supplied Encryption Key mechanism used to store an Object's data at rest.

Fields
encryption_algorithm

string

Optional. The encryption algorithm.
key_sha256_bytes

bytes

Optional. SHA256 hash value of the encryption key. In raw bytes format (not base64-encoded).

DeleteBucketRequest

Request message for DeleteBucket.

Fields
name

string

Required. Name of a bucket to delete.
if_metageneration_match

int64

If set, only deletes the bucket if its metageneration matches this value.
if_metageneration_not_match

int64

If set, only deletes the bucket if its metageneration does not match this value.

DeleteObjectRequest

Request message for deleting an object.

Fields
bucket

string

Required. Name of the bucket in which the object resides.
object

string

Required. The name of the finalized object to delete. Note: If you want to delete an unfinalized resumable upload please use CancelResumableWrite.
generation

int64

Optional. If present, permanently deletes a specific revision of this object (as opposed to the latest version, the default).
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.

GetBucketRequest

Request message for GetBucket.

Fields
name

string

Required. Name of a bucket.
if_metageneration_match

int64

If set, only gets the bucket metadata if its metageneration matches this value.
if_metageneration_not_match

int64

If set, only gets the bucket metadata if its metageneration does not match this value.
read_mask

FieldMask

Mask specifying which fields to read. A "*" field may be used to indicate all fields. If no mask is specified, it defaults to all fields.

GetObjectRequest

Request message for GetObject.

Fields
bucket

string

Required. Name of the bucket in which the object resides.
object

string

Required. Name of the object.
generation

int64

Optional. If present, selects a specific revision of this object (as opposed to the latest version, the default).
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
restore_token

string

Optional. Restore token used to differentiate soft-deleted objects with the same name and generation. Only applicable for hierarchical namespace buckets and if soft_deleted is set to true. This parameter is optional, and is only required in the rare case when there are multiple soft-deleted objects with the same name and generation.
soft_deleted

bool

If true, return the soft-deleted version of this object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.
read_mask

FieldMask

Mask specifying which fields to read. If no mask is specified, will default to all fields except metadata.acl and metadata.owner. * may be used to mean "all fields".

ListBucketsRequest

Request message for ListBuckets.

Fields
parent

string

Required. The project whose buckets we are listing.
page_size

int32

Optional. Maximum number of buckets to return in a single response. The service will use this parameter or 1,000 items, whichever is smaller. If acl is present in the read_mask, the service uses this parameter of 200 items, whichever is smaller.
page_token

string

Optional. A previously-returned page token representing part of the larger set of results to view.
prefix

string

Optional. Filter results to buckets whose names begin with this prefix.
read_mask

FieldMask

Mask specifying which fields to read from each result. If no mask is specified, will default to all fields except items.owner, items.acl, and items.default_object_acl. * may be used to mean "all fields".

ListBucketsResponse

Response message for ListBuckets.

Fields
buckets[]

Bucket

The list of items.
next_page_token

string

The continuation token, used to page through large result sets. Provide this value in a subsequent request to return the next page of results.

ListObjectsRequest

Request message for ListObjects.

Fields
parent

string

Required. Name of the bucket in which to look for objects.
page_size

int32

Optional. Maximum number of items plus prefixes to return in a single page of responses. As duplicate prefixes are omitted, fewer total results may be returned than requested. The service uses this parameter or 1,000 items, whichever is smaller.
page_token

string

Optional. A previously-returned page token representing part of the larger set of results to view.
delimiter

string

Optional. If set, returns results in a directory-like mode. items will contain only objects whose names, aside from the prefix, do not contain delimiter. Objects whose names, aside from the prefix, contain delimiter will have their name, truncated after the delimiter, returned in prefixes. Duplicate prefixes are omitted.
include_trailing_delimiter

bool

Optional. If true, objects that end in exactly one instance of delimiter will have their metadata included in items in addition to prefixes.
prefix

string

Optional. Filter results to objects whose names begin with this prefix.
versions

bool

Optional. If true, lists all versions of an object as distinct results. For more information, see Object Versioning.
lexicographic_start

string

Optional. Filter results to objects whose names are lexicographically equal to or after lexicographic_start. If lexicographic_end is also set, the objects listed have names between lexicographic_start (inclusive) and lexicographic_end (exclusive).
lexicographic_end

string

Optional. Filter results to objects whose names are lexicographically before lexicographic_end. If lexicographic_start is also set, the objects listed have names between lexicographic_start (inclusive) and lexicographic_end (exclusive).
soft_deleted

bool

Optional. If true, only list all soft-deleted versions of the object. Soft delete policy is required to set this option.
include_folders_as_prefixes

bool

Optional. If true, include all folders and managed folders (besides objects) in the returned prefixes. Requires delimiter to be set to '/'.
match_glob

string

Optional. Filter results to objects and prefixes that match this glob pattern. See List objects using glob for the full syntax.
read_mask

FieldMask

Mask specifying which fields to read from each result. If no mask is specified, will default to all fields except items.acl and items.owner. * may be used to read all fields.

ListObjectsResponse

Response message for ListObjects.

Fields
objects[]

Object

The list of items.
prefixes[]

string

The list of prefixes of objects matching-but-not-listed up to and including the requested delimiter.
next_page_token

string

The continuation token, used to page through large result sets. Provide this value in a subsequent request to return the next page of results.

LockBucketRetentionPolicyRequest

Request message for LockBucketRetentionPolicyRequest.

Fields
bucket

string

Required. Name of a bucket.
if_metageneration_match

int64

Required. Makes the operation conditional on whether bucket's current metageneration matches the given value. Must be positive.

MoveObjectRequest

Request message for MoveObject.

Fields
bucket

string

Required. Name of the bucket in which the object resides.
source_object

string

Required. Name of the source object.
destination_object

string

Required. Name of the destination object.
if_source_generation_match

int64

Optional. Makes the operation conditional on whether the source object's current generation matches the given value. if_source_generation_match and if_source_generation_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_source_generation_not_match

int64

Optional. Makes the operation conditional on whether the source object's current generation does not match the given value. if_source_generation_match and if_source_generation_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_source_metageneration_match

int64

Optional. Makes the operation conditional on whether the source object's current metageneration matches the given value. if_source_metageneration_match and if_source_metageneration_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_source_metageneration_not_match

int64

Optional. Makes the operation conditional on whether the source object's current metageneration does not match the given value. if_source_metageneration_match and if_source_metageneration_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_generation_match

int64

Optional. Makes the operation conditional on whether the destination object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object. if_generation_match and if_generation_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_generation_not_match

int64

Optional. Makes the operation conditional on whether the destination object's current generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object. if_generation_match and if_generation_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_metageneration_match

int64

Optional. Makes the operation conditional on whether the destination object's current metageneration matches the given value. if_metageneration_match and if_metageneration_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.
if_metageneration_not_match

int64

Optional. Makes the operation conditional on whether the destination object's current metageneration does not match the given value. if_metageneration_match and if_metageneration_not_match conditions are mutually exclusive: it's an error for both of them to be set in the request.

Object

An object.

Fields
name

string

Immutable. The name of this object. Nearly any sequence of unicode characters is valid. See Guidelines. Example: test.txt The name field by itself does not uniquely identify a Cloud Storage object. A Cloud Storage object is uniquely identified by the tuple of (bucket, object, generation).
bucket

string

Immutable. The name of the bucket containing this object.
etag

string

Optional. The etag of the object. If included in the metadata of an update or delete request message, the operation will only be performed if the etag matches that of the live object.
generation

int64

Immutable. The content generation of this object. Used for object versioning.
metageneration

int64

Output only. The version of the metadata for this generation of this object. Used for preconditions and for detecting changes in metadata. A metageneration number is only meaningful in the context of a particular generation of a particular object.
storage_class

string

Optional. Storage class of the object.
size

int64

Output only. Content-Length of the object data in bytes, matching RFC 7230 §3.3.2.
content_encoding

string

Optional. Content-Encoding of the object data, matching RFC 7231 §3.1.2.2
content_disposition

string

Optional. Content-Disposition of the object data, matching RFC 6266.
cache_control

string

Optional. Cache-Control directive for the object data, matching RFC 7234 §5.2. If omitted, and the object is accessible to all anonymous users, the default is public, max-age=3600.
acl[]

ObjectAccessControl

Optional. Access controls on the object. If iam_config.uniform_bucket_level_access is enabled on the parent bucket, requests to set, read, or modify acl is an error.
content_language

string

Optional. Content-Language of the object data, matching RFC 7231 §3.1.3.2.
delete_time

Timestamp

Output only. If this object is noncurrent, this is the time when the object became noncurrent.
finalize_time

Timestamp

Output only. The time when the object was finalized.
content_type

string

Optional. Content-Type of the object data, matching RFC 7231 §3.1.1.5. If an object is stored without a Content-Type, it is served as application/octet-stream.
create_time

Timestamp

Output only. The creation time of the object.
component_count

int32

Output only. Number of underlying components that make up this object. Components are accumulated by compose operations.
checksums

ObjectChecksums

Output only. Hashes for the data part of this object. This field is used for output only and is silently ignored if provided in requests. The checksums of the complete object regardless of data range. If the object is downloaded in full, the client should compute one of these checksums over the downloaded object and compare it against the value provided here.
update_time

Timestamp

Output only. The modification time of the object metadata. Set initially to object creation time and then updated whenever any metadata of the object changes. This includes changes made by a requester, such as modifying custom metadata, as well as changes made by Cloud Storage on behalf of a requester, such as changing the storage class based on an Object Lifecycle Configuration.
kms_key

string

Optional. Cloud KMS Key used to encrypt this object, if the object is encrypted by such a key.
update_storage_class_time

Timestamp

Output only. The time at which the object's storage class was last changed. When the object is initially created, it is set to time_created.
temporary_hold

bool

Optional. Whether an object is under temporary hold. While this flag is set to true, the object is protected against deletion and overwrites. A common use case of this flag is regulatory investigations where objects need to be retained while the investigation is ongoing. Note that unlike event-based hold, temporary hold does not impact retention expiration time of an object.
retention_expire_time

Timestamp

Optional. A server-determined value that specifies the earliest time that the object's retention period expires. Note 1: This field is not provided for objects with an active event-based hold, since retention expiration is unknown until the hold is removed. Note 2: This value can be provided even when temporary hold is set (so that the user can reason about policy without having to first unset the temporary hold).
metadata

map<string, string>

Optional. User-provided metadata, in key/value pairs.
owner

Owner

Output only. The owner of the object. This will always be the uploader of the object.
customer_encryption

CustomerEncryption

Optional. Metadata of Customer-Supplied Encryption Key, if the object is encrypted by such a key.
custom_time

Timestamp

Optional. A user-specified timestamp set on an object.
retention

Retention

Optional. Retention configuration of this object. May only be configured if the bucket has object retention enabled.
restore_token

string

Output only. Restore token used to differentiate deleted objects with the same name and generation. This field is output only, and only set for deleted objects in HNS buckets.
event_based_hold

bool

Whether an object is under event-based hold. An event-based hold is a way to force the retention of an object until after some event occurs. Once the hold is released by explicitly setting this field to false, the object becomes subject to any bucket-level retention policy, except that the retention duration is calculated from the time the event based hold was lifted, rather than the time the object was created.

In a WriteObject request, not setting this field implies that the value should be taken from the parent bucket's "default_event_based_hold" field. In a response, this field will always be set to true or false.
soft_delete_time

Timestamp

Output only. This is the time when the object became soft-deleted.

Soft-deleted objects are only accessible if a soft_delete_policy is enabled. Also see hard_delete_time.
hard_delete_time

Timestamp

Output only. The time when the object is permanently deleted.

Only set when an object becomes soft-deleted with a soft_delete_policy. Otherwise, the object will not be accessible.

Retention

Specifies retention parameters of the object. Objects under retention cannot be deleted or overwritten until their retention expires.

Fields
mode

Mode

Optional. The mode of the Retention.
retain_until_time

Timestamp

Optional. The timestamp that the object needs to be retained until. Value cannot be set in the past or more than 100 years in the future.

Mode

Retention mode values.

Enums
MODE_UNSPECIFIED No specified mode. Object is not under retention.
UNLOCKED Retention period may be decreased or increased. The Retention configuration may be removed. The mode may be changed to locked.
LOCKED Retention period may be increased. The Retention configuration cannot be removed. The mode cannot be changed.

ObjectAccessControl

An access-control entry.

Fields
role

string

Optional. The access permission for the entity. One of the following values: * READER * WRITER * OWNER
id

string

Optional. The ID of the access-control entry.
entity

string

Optional. The entity holding the permission, in one of the following forms: * user-{userid} * user-{email} * group-{groupid} * group-{email} * domain-{domain} * project-{team}-{projectnumber} * 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. * All members of the Google Apps for Business domain example.com would be domain-example.com. For project entities, project-{team}-{projectnumber} format is returned on response.
entity_alt

string

Output only. The alternative entity format, if exists. For project entities, project-{team}-{projectid} format is returned on response.
entity_id

string

Optional. The ID for the entity, if any.
etag

string

Optional. The etag of the ObjectAccessControl. If included in the metadata of an update or delete request message, the operation will only be performed if the etag matches that of the live object's ObjectAccessControl.
email

string

Optional. The email address associated with the entity, if any.
domain

string

Optional. The domain associated with the entity, if any.
project_team

ProjectTeam

Optional. The project team associated with the entity, if any.

ObjectChecksums

Message used for storing full (not subrange) object checksums.

Fields
md5_hash

bytes

Optional. 128 bit MD5 hash of the object data. For more information about using the MD5 hash, see Data validation and change detection. Not all objects will provide an MD5 hash. For example, composite objects provide only crc32c hashes. This value is equivalent to running cat object.txt | openssl md5 -binary
crc32c

fixed32

CRC32C digest of the object data. Computed by the Cloud Storage service for all written objects. If set in a WriteObjectRequest, service will validate that the stored object matches this checksum.

ObjectRangeData

Contains data and metadata for a range of an object.

Fields
checksummed_data

ChecksummedData

A portion of the data for the object.
read_range

ReadRange

The ReadRange describes the content being returned with read_id set to the corresponding ReadObjectRequest in the stream. Multiple ObjectRangeData messages may have the same read_id but increasing offsets. ReadObjectResponse messages with the same read_id are guaranteed to be delivered in increasing offset order.
range_end

bool

If set, indicates there are no more bytes to read for the given ReadRange.

Owner

The owner of a specific resource.

Fields
entity

string

Optional. The entity, in the form user-*userId*.
entity_id

string

Optional. The ID for the entity.

ProjectTeam

Represents the Viewers, Editors, or Owners of a given project.

Fields
project_number

string

Optional. The project number.
team

string

Optional. The team.

QueryWriteStatusRequest

Request object for QueryWriteStatus.

Fields
upload_id

string

Required. The name of the resume token for the object whose write status is being requested.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.

QueryWriteStatusResponse

Response object for QueryWriteStatus.

Fields
Union field write_status. The response sets one of the following. write_status can be only one of the following:
persisted_size

int64

The total number of bytes that have been processed for the given object from all WriteObject calls. This is the correct value for the 'write_offset' field to use when resuming the WriteObject operation. Only set if the upload has not finalized.
resource

Object

A resource containing the metadata for the uploaded object. Only set if the upload has finalized.

ReadObjectRequest

Request message for ReadObject.

Fields
bucket

string

Required. The name of the bucket containing the object to read.
object

string

Required. The name of the object to read.
generation

int64

Optional. If present, selects a specific revision of this object (as opposed to the latest version, the default).
read_offset

int64

Optional. The offset for the first byte to return in the read, relative to the start of the object.

A negative read_offset value is interpreted as the number of bytes back from the end of the object to be returned. For example, if an object's length is 15 bytes, a ReadObjectRequest with read_offset = -5 and read_limit = 3 would return bytes 10 through 12 of the object. Requesting a negative offset with magnitude larger than the size of the object will return the entire object.
read_limit

int64

Optional. The maximum number of data bytes the server is allowed to return in the sum of all Object messages. A read_limit of zero indicates that there is no limit, and a negative read_limit causes an error.

If the stream returns fewer bytes than allowed by the read_limit and no error occurred, the stream includes all data from the read_offset to the end of the resource.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.
read_mask

FieldMask

Mask specifying which fields to read. The checksummed_data field and its children will always be present. If no mask is specified, will default to all fields except metadata.owner and metadata.acl. * may be used to mean "all fields".

ReadObjectResponse

Response message for ReadObject.

Fields
checksummed_data

ChecksummedData

A portion of the data for the object. The service may leave data empty for any given ReadResponse. This enables the service to inform the client that the request is still live while it is running an operation to generate more data.
object_checksums

ObjectChecksums

The checksums of the complete object. If the object is downloaded in full, the client should compute one of these checksums over the downloaded object and compare it against the value provided here.
content_range

ContentRange

If read_offset and or read_limit was specified on the ReadObjectRequest, ContentRange is populated on the first ReadObjectResponse message of the read stream.
metadata

Object

Metadata of the object whose media is being returned. Only populated in the first response in the stream.

ReadRange

Describes a range of bytes to read in a BidiReadObjectRanges request.

Fields
read_offset

int64

Required. The offset for the first byte to return in the read, relative to the start of the object.

A negative read_offset value is interpreted as the number of bytes back from the end of the object to be returned. For example, if an object's length is 15 bytes, a ReadObjectRequest with read_offset = -5 and read_length = 3 would return bytes 10 through 12 of the object. Requesting a negative offset with magnitude larger than the size of the object will return the entire object. A read_offset larger than the size of the object will result in an OutOfRange error.
read_length

int64

Optional. The maximum number of data bytes the server is allowed to return across all response messages with the same read_id. A read_length of zero indicates to read until the resource end, and a negative read_length will cause an error. If the stream returns fewer bytes than allowed by the read_length and no error occurred, the stream includes all data from the read_offset to the resource end.
read_id

int64

Required. Read identifier provided by the client. When the client issues more than one outstanding ReadRange on the same stream, responses can be mapped back to their corresponding requests using this value. Clients must ensure that all outstanding requests have different read_id values. The server may close the stream with an error if this condition is not met.

ReadRangeError

Error extension proto containing details for a single range read

Fields
read_id

int64

The id of the corresponding read_range
status

Status

The status which should be an enum value of google.rpc.Code.

RestoreObjectRequest

Request message for RestoreObject.

Fields
bucket

string

Required. Name of the bucket in which the object resides.
object

string

Required. The name of the object to restore.
generation

int64

Required. The specific revision of the object to restore.
restore_token

string

Optional. Restore token used to differentiate soft-deleted objects with the same name and generation. Only applicable for hierarchical namespace buckets. This parameter is optional, and is only required in the rare case when there are multiple soft-deleted objects with the same name and generation.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.
copy_source_acl

bool

If false or unset, the bucket's default object ACL is used. If true, copy the source object's access controls. Return an error if bucket has UBLA enabled.

RewriteObjectRequest

Request message for RewriteObject. If the source object is encrypted using a Customer-Supplied Encryption Key the key information must be provided in the copy_source_encryption_algorithm, copy_source_encryption_key_bytes, and copy_source_encryption_key_sha256_bytes fields. If the destination object should be encrypted the keying information should be provided in the encryption_algorithm, encryption_key_bytes, and encryption_key_sha256_bytes fields of the common_object_request_params.customer_encryption field.

Fields
destination_name

string

Required. Immutable. The name of the destination object. See the Naming Guidelines. Example: test.txt The name field by itself does not uniquely identify a Cloud Storage object. A Cloud Storage object is uniquely identified by the tuple of (bucket, object, generation).
destination_bucket

string

Required. Immutable. The name of the bucket containing the destination object.
destination_kms_key

string

Optional. The name of the Cloud KMS key that is used to encrypt the destination object. The Cloud KMS key must be located in same location as the object. If the parameter is not specified, the request uses the destination bucket's default encryption key, if any, or else the Google-managed encryption key.
destination

Object

Optional. Properties of the destination, post-rewrite object. The name, bucket and kms_key fields must not be populated (these values are specified in the destination_name, destination_bucket, and destination_kms_key fields). If destination is present it is used to construct the destination object's metadata; otherwise the destination object's metadata is copied from the source object.
source_bucket

string

Required. Name of the bucket in which to find the source object.
source_object

string

Required. Name of the source object.
source_generation

int64

Optional. If present, selects a specific revision of the source object (as opposed to the latest version, the default).
rewrite_token

string

Optional. Include this field (from the previous rewrite response) on each rewrite request after the first one, until the rewrite response 'done' flag is true. Calls that provide a rewriteToken can omit all other request fields, but if included those fields must match the values provided in the first rewrite request.
destination_predefined_acl

string

Optional. Apply a predefined set of access controls to the destination object. Valid values are "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
max_bytes_rewritten_per_call

int64

Optional. The maximum number of bytes that are rewritten per rewrite request. Most callers shouldn't need to specify this parameter - it is primarily in place to support testing. If specified the value must be an integral multiple of 1 MiB (1048576). Also, this only applies to requests where the source and destination span locations and/or storage classes. Finally, this value must not change across rewrite calls else you'll get an error that the rewriteToken is invalid.
copy_source_encryption_algorithm

string

Optional. The algorithm used to encrypt the source object, if any. Used if the source object was encrypted with a Customer-Supplied Encryption Key.
copy_source_encryption_key_bytes

bytes

Optional. The raw bytes (not base64-encoded) AES-256 encryption key used to encrypt the source object, if it was encrypted with a Customer-Supplied Encryption Key.
copy_source_encryption_key_sha256_bytes

bytes

Optional. The raw bytes (not base64-encoded) SHA256 hash of the encryption key used to encrypt the source object, if it was encrypted with a Customer-Supplied Encryption Key.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
object_checksums

ObjectChecksums

Optional. The checksums of the complete object. This is used to validate the destination object after rewriting.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

Makes the operation conditional on whether the destination object's current metageneration matches the given value.
if_metageneration_not_match

int64

Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
if_source_generation_match

int64

Makes the operation conditional on whether the source object's live generation matches the given value.
if_source_generation_not_match

int64

Makes the operation conditional on whether the source object's live generation does not match the given value.
if_source_metageneration_match

int64

Makes the operation conditional on whether the source object's current metageneration matches the given value.
if_source_metageneration_not_match

int64

Makes the operation conditional on whether the source object's current metageneration does not match the given value.

RewriteResponse

A rewrite response.

Fields
total_bytes_rewritten

int64

The total bytes written so far, which can be used to provide a waiting user with a progress indicator. This property is always present in the response.
object_size

int64

The total size of the object being copied in bytes. This property is always present in the response.
done

bool

true if the copy is finished; otherwise, false if the copy is in progress. This property is always present in the response.
rewrite_token

string

A token to use in subsequent requests to continue copying data. This token is present in the response only when there is more data to copy.
resource

Object

A resource containing the metadata for the copied-to object. This property is present in the response only when copying completes.

ServiceConstants

This type has no fields.

Shared constants.

Values

A collection of constant values meaningful to the Storage API.

Enums
VALUES_UNSPECIFIED Unused. Proto3 requires first enum to be 0.
MAX_READ_CHUNK_BYTES The maximum size chunk that can be returned in a single ReadRequest. 2 MiB.
MAX_WRITE_CHUNK_BYTES The maximum size chunk that can be sent in a single WriteObjectRequest. 2 MiB.
MAX_OBJECT_SIZE_MB The maximum size of an object in MB - whether written in a single stream or composed from multiple other objects. 5 TiB.
MAX_CUSTOM_METADATA_FIELD_NAME_BYTES The maximum length field name that can be sent in a single custom metadata field. 1 KiB.
MAX_CUSTOM_METADATA_FIELD_VALUE_BYTES The maximum length field value that can be sent in a single custom_metadata field. 4 KiB.
MAX_CUSTOM_METADATA_TOTAL_SIZE_BYTES The maximum total bytes that can be populated into all field names and values of the custom_metadata for one object. 8 KiB.
MAX_BUCKET_METADATA_TOTAL_SIZE_BYTES The maximum total bytes that can be populated into all bucket metadata fields. 20 KiB.
MAX_NOTIFICATION_CONFIGS_PER_BUCKET The maximum number of NotificationConfigs that can be registered for a given bucket.
MAX_LIFECYCLE_RULES_PER_BUCKET The maximum number of LifecycleRules that can be registered for a given bucket.
MAX_NOTIFICATION_CUSTOM_ATTRIBUTES The maximum number of custom attributes per NotificationConfigs.
MAX_NOTIFICATION_CUSTOM_ATTRIBUTE_KEY_LENGTH The maximum length of a custom attribute key included in NotificationConfig.
MAX_NOTIFICATION_CUSTOM_ATTRIBUTE_VALUE_LENGTH The maximum length of a custom attribute value included in a NotificationConfig.
MAX_LABELS_ENTRIES_COUNT The maximum number of key/value entries per bucket label.
MAX_LABELS_KEY_VALUE_LENGTH The maximum character length of the key or value in a bucket label map.
MAX_LABELS_KEY_VALUE_BYTES The maximum byte size of the key or value in a bucket label map.
MAX_OBJECT_IDS_PER_DELETE_OBJECTS_REQUEST The maximum number of object IDs that can be included in a DeleteObjectsRequest.
SPLIT_TOKEN_MAX_VALID_DAYS The maximum number of days for which a token returned by the GetListObjectsSplitPoints RPC is valid.

StartResumableWriteRequest

Request message for StartResumableWrite.

Fields
write_object_spec

WriteObjectSpec

Required. Contains the information necessary to start a resumable write.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests related to an object.
object_checksums

ObjectChecksums

Optional. The checksums of the complete object. This is used to validate the uploaded object. For each upload, object_checksums can be provided when initiating a resumable upload withStartResumableWriteRequest or when completing a write with WriteObjectRequest with finish_write set to true.

StartResumableWriteResponse

Response object for StartResumableWrite.

Fields
upload_id

string

A unique identifier for the initiated resumable write operation. As the ID grants write access, you should keep it confidential during the upload to prevent unauthorized access and data tampering during your upload. This ID should be included in subsequent WriteObject requests to upload the object data.

UpdateBucketRequest

Request for UpdateBucket method.

Fields
bucket

Bucket

Required. The bucket to update. The bucket's name field is used to identify the bucket.
predefined_acl

string

Optional. Apply a predefined set of access controls to this bucket. Valid values are "authenticatedRead", "private", "projectPrivate", "publicRead", or "publicReadWrite".
predefined_default_object_acl

string

Optional. Apply a predefined set of default object access controls to this bucket. Valid values are authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, or publicRead.
update_mask

FieldMask

Required. List of fields to be updated.

To specify ALL fields, equivalent to the JSON API's "update" function, specify a single field with the value *. Note: not recommended. If a new field is introduced at a later time, an older client updating with the * may accidentally reset the new field's value.

Not specifying any fields is an error.
if_metageneration_match

int64

If set, the request modifies the bucket if its metageneration matches this value.
if_metageneration_not_match

int64

If set, the request modifies the bucket if its metageneration does not match this value.

UpdateObjectRequest

Request message for UpdateObject.

Fields
object

Object

Required. The object to update. The object's bucket and name fields are used to identify the object to update. If present, the object's generation field selects a specific revision of this object whose metadata should be updated. Otherwise, assumes the live version of the object.
predefined_acl

string

Optional. Apply a predefined set of access controls to this object. Valid values are "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
update_mask

FieldMask

Required. List of fields to be updated.

To specify ALL fields, equivalent to the JSON API's "update" function, specify a single field with the value *. Note: not recommended. If a new field is introduced at a later time, an older client updating with the * may accidentally reset the new field's value.

Not specifying any fields is an error.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
override_unlocked_retention

bool

Optional. Overrides the unlocked retention config on the object.
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.

WriteObjectRequest

Request message for WriteObject.

Fields
write_offset

int64

Required. The offset from the beginning of the object at which the data should be written.

In the first WriteObjectRequest of a WriteObject() action, it indicates the initial offset for the Write() call. The value must be equal to the persisted_size that a call to QueryWriteStatus() would return (0 if this is the first write to the object).

On subsequent calls, this value must be no larger than the sum of the first write_offset and the sizes of all data chunks sent previously on this stream.

An incorrect value will cause an error.
object_checksums

ObjectChecksums

Optional. Checksums for the complete object. If the checksums computed by the service don't match the specified checksums the call will fail. May only be provided in the first or last request (either with first_message, or finish_write set).
finish_write

bool

Optional. If true, this indicates that the write is complete. Sending any WriteObjectRequests subsequent to one in which finish_write is true will cause an error. For a non-resumable write (where the upload_id was not set in the first message), it is an error not to set this field in the final message of the stream.
common_object_request_params

CommonObjectRequestParams

Optional. A set of parameters common to Storage API requests concerning an object.
Union field first_message. The first message of each stream should set one of the following. first_message can be only one of the following:
upload_id

string

For resumable uploads. This should be the upload_id returned from a call to StartResumableWriteResponse.
write_object_spec

WriteObjectSpec

For non-resumable uploads. Describes the overall upload, including the destination bucket and object name, preconditions, etc.
Union field data. A portion of the data for the object. data can be only one of the following:
checksummed_data

ChecksummedData

The data to insert. If a crc32c checksum is provided that doesn't match the checksum computed by the service, the request will fail.

WriteObjectResponse

Response message for WriteObjectResponse.

Fields
Union field write_status. The response will set one of the following. write_status can be only one of the following:
persisted_size

int64

The total number of bytes that have been processed for the given object from all WriteObject calls. Only set if the upload has not finalized.
resource

Object

A resource containing the metadata for the uploaded object. Only set if the upload has finalized.

WriteObjectSpec

Describes an attempt to insert an object, possibly over multiple requests.

Fields
resource

Object

Required. Destination object, including its name and its metadata.
predefined_acl

string

Optional. Apply a predefined set of access controls to this object. Valid values are "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
if_generation_match

int64

Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
if_generation_not_match

int64

Makes the operation conditional on whether the object's live generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object.
if_metageneration_match

int64

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

int64

Makes the operation conditional on whether the object's current metageneration does not match the given value.
object_size

int64

The expected final object size being uploaded. If this value is set, closing the stream after writing fewer or more than object_size bytes will result in an OUT_OF_RANGE error.

This situation is considered a client error, and if such an error occurs you must start the upload over from scratch, this time sending the correct number of bytes.
appendable

bool

If true, the object is created in appendable mode. This field may only be set when using BidiWriteObject.