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 [email protected] would be [email protected]. * The group [email protected] would be [email protected] * 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