Package google.storage.v2

Index

Storage (interface)
DeleteObjectRequest (message)
GetObjectRequest (message)
ListObjectsRequest (message)
ListObjectsResponse (message)
QueryWriteStatusRequest (message)
QueryWriteStatusResponse (message)
ReadObjectRequest (message)
ReadObjectResponse (message)
RestoreObjectRequest (message)
StartResumableWriteRequest (message)
StartResumableWriteResponse (message)
WriteObjectRequest (message)
WriteObjectResponse (message)
WriteObjectSpec (message)

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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

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

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.

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 `WriteObjectRequest`s 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

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.

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.