Package google.storage.v2

Index

Storage

API Overview and Naming Syntax

The Cloud Storage RPC API allows applications to read and write data through the abstractions of buckets and objects. For a description of these abstractions see https://cloud.google.com/storage/docs.

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

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

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.
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 (e.g., increase the timeouts, stop using more than one process to perform the upload, etc.), and then should 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 will skip 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 will 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 will cause an error. The client should check the response it receives to determine how much data the service was able to commit and whether the service views the object as complete.

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

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.

CommonObjectRequestParams

Parameters that can be passed to any object request.

Fields
encryption_algorithm

string

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

bytes

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

bytes

SHA256 hash of encryption key used with the Customer-Supplied Encryption Keys feature.

DeleteObjectRequest

Message for deleting an object. bucket and object must be set.

Fields
bucket

string

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

string

Required. The name of the finalized object to delete. For information about how to URL encode object names to be path safe, see Encoding URI path parts.

Note: If you want to delete an unfinalized resumable upload please use CancelResumableWrite.
generation

int64

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

CommonObjectRequestParams

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.

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. For information about how to URL encode object names to be path safe, see Encoding URI path parts.
generation

int64

If present, selects a specific revision of this object (as opposed to the latest version, the default). If softDeleted is true, this parameter is required.
common_object_request_params

CommonObjectRequestParams

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, returns the metadata of the soft-deleted 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".

ListObjectsRequest

Request message for ListObjects.

Fields
parent

string

Required. Name of the bucket in which the objects are located.
page_size

int32

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 will use this parameter or 1,000 items, whichever is smaller.
page_token

string

If you start a listing and then create an object in the bucket before using a pageToken to continue listing, you do not see the new object in the subsequent listing results if it is in part of the object namespace already listed.
delimiter

string

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

bool

If true, objects that end in exactly one instance of delimiter have their metadata included in items in addition to the relevant part of the object name appearing in prefixes.
prefix

string

Filter results to include only objects whose names begin with this prefix. When prefix is set, the names of the objects returned in the response are relative to the root of the bucket.
versions

bool

If true, lists all versions of an object as distinct results in order of increasing generation number. The default value for versions is false. 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, will also include 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 mean "all fields".

ListObjectsResponse

The result of a call to Objects.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.

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

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

Storage class of the object.
size

int64

Output only. Content-Length of the object data in bytes, matching [https://tools.ietf.org/html/rfc7230#section-3.3.2][RFC 7230 §3.3.2].
content_encoding

string

Content-Encoding of the object data, matching [https://tools.ietf.org/html/rfc7231#section-3.1.2.2][RFC 7231 §3.1.2.2]
content_disposition

string

Content-Disposition of the object data, matching [https://tools.ietf.org/html/rfc6266][RFC 6266].
cache_control

string

Cache-Control directive for the object data, matching [https://tools.ietf.org/html/rfc7234#section-5.2"][RFC 7234 §5.2]. If omitted, and the object is accessible to all anonymous users, the default will be public, max-age=3600.
acl[]

ObjectAccessControl

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

Content-Language of the object data, matching [https://tools.ietf.org/html/rfc7231#section-3.1.3.2][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.
content_type

string

Content-Type of the object data, matching [https://tools.ietf.org/html/rfc7231#section-3.1.1.5][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 will be 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

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 will be set to time_created.
temporary_hold

bool

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

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>

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

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

Timestamp

A user-specified timestamp set on an object.
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 will become subject to any bucket-level retention policy, except that the retention duration will be 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 will be permanently deleted.

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

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

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

QueryWriteStatusResponse

Response object for QueryWriteStatus.

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

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

int64

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

A negative read_offset value will be 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

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 will cause 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

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 will be 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.

RestoreObjectRequest

Message for restoring an object. bucket, object, and generation must be set.

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

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 will be used. If true, copy the source object's access controls. Return an error if bucket has UBLA enabled.

StartResumableWriteRequest

Request message StartResumableWrite.

Fields
write_object_spec

WriteObjectSpec

Required. The destination bucket, object, and metadata, as well as any preconditions.
common_object_request_params

CommonObjectRequestParams

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

ObjectChecksums

The checksums of the complete object. This will be used to validate the uploaded object. For each upload, object_checksums can be provided with either StartResumableWriteRequest or the WriteObjectRequest with finish_write set to true.

StartResumableWriteResponse

Response object for StartResumableWrite.

Fields
upload_id

string

The upload_id of the newly started resumable write operation. This value should be copied into the WriteObjectRequest.upload_id field.

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 causes an error.
object_checksums

ObjectChecksums

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

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

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

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

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.