// Copyright 2026 Google LLC

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

syntax = "proto3";

package google.storage.v2;

import "google/api/client.proto";

import "google/api/field_behavior.proto";

import "google/api/resource.proto";

import "google/api/routing.proto";

import "google/iam/v1/iam_policy.proto";

import "google/iam/v1/policy.proto";

import "google/protobuf/duration.proto";

import "google/protobuf/empty.proto";

import "google/protobuf/field_mask.proto";

import "google/protobuf/timestamp.proto";

import "google/rpc/status.proto";

import "google/type/date.proto";

option go_package = "cloud.google.com/go/storage/internal/apiv2/storagepb;storagepb";

option java_multiple_files = true;

option java_outer_classname = "StorageProto";

option java_package = "com.google.storage.v2";

option (google.api.resource_definition) = {

type: "cloudkms.googleapis.com/CryptoKey"

pattern: "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}"

};

// ## 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](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, `_` might 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).

service Storage {

option (google.api.default_host) = "storage.googleapis.com";

option (google.api.oauth_scopes) =

"https://www.googleapis.com/auth/cloud-platform,"

"https://www.googleapis.com/auth/cloud-platform.read-only,"

"https://www.googleapis.com/auth/devstorage.full_control,"

"https://www.googleapis.com/auth/devstorage.read_only,"

"https://www.googleapis.com/auth/devstorage.read_write";

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

rpc DeleteBucket(DeleteBucketRequest) returns (google.protobuf.Empty) {

option (google.api.routing) = {

routing_parameters { field: "name" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "name";

}

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

rpc GetBucket(GetBucketRequest) returns (Bucket) {

option (google.api.routing) = {

routing_parameters { field: "name" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "name";

}

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

rpc CreateBucket(CreateBucketRequest) returns (Bucket) {

option (google.api.routing) = {

routing_parameters { field: "parent" path_template: "{project=**}" }

routing_parameters {

field: "bucket.project"

path_template: "{project=**}"

}

};

option (google.api.method_signature) = "parent,bucket,bucket_id";

}

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

rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse) {

option (google.api.routing) = {

routing_parameters { field: "parent" path_template: "{project=**}" }

};

option (google.api.method_signature) = "parent";

}

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

rpc LockBucketRetentionPolicy(LockBucketRetentionPolicyRequest)

returns (Bucket) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket";

}

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

rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)

returns (google.iam.v1.Policy) {

option (google.api.routing) = {

routing_parameters { field: "resource" path_template: "{bucket=**}" }

routing_parameters {

field: "resource"

path_template: "{bucket=projects/*/buckets/*}/**"

}

};

option (google.api.method_signature) = "resource";

}

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

rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)

returns (google.iam.v1.Policy) {

option (google.api.routing) = {

routing_parameters { field: "resource" path_template: "{bucket=**}" }

routing_parameters {

field: "resource"

path_template: "{bucket=projects/*/buckets/*}/**"

}

};

option (google.api.method_signature) = "resource,policy";

}

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

rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)

returns (google.iam.v1.TestIamPermissionsResponse) {

option (google.api.routing) = {

routing_parameters { field: "resource" path_template: "{bucket=**}" }

routing_parameters {

field: "resource"

path_template: "{bucket=projects/*/buckets/*}/objects/**"

}

routing_parameters {

field: "resource"

path_template: "{bucket=projects/*/buckets/*}/managedFolders/**"

}

};

option (google.api.method_signature) = "resource,permissions";

}

// Updates a bucket. Changes to the bucket are readable immediately after

// writing, but configuration changes might 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`

rpc UpdateBucket(UpdateBucketRequest) returns (Bucket) {

option (google.api.routing) = {

routing_parameters { field: "bucket.name" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket,update_mask";

}

// Concatenates a list of existing objects into a new object in the same

// bucket. The existing source objects are unaffected by this operation.

//

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

rpc ComposeObject(ComposeObjectRequest) returns (Object) {

option (google.api.routing) = {

routing_parameters {

field: "destination.bucket"

path_template: "{bucket=**}"

}

};

}

// 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`][google.storage.v2.Storage.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.

rpc DeleteObject(DeleteObjectRequest) returns (google.protobuf.Empty) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket,object";

option (google.api.method_signature) = "bucket,object,generation";

}

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

rpc RestoreObject(RestoreObjectRequest) returns (Object) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket,object,generation";

}

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

rpc CancelResumableWrite(CancelResumableWriteRequest)

returns (CancelResumableWriteResponse) {

option (google.api.routing) = {

routing_parameters {

field: "upload_id"

path_template: "{bucket=projects/*/buckets/*}/**"

}

};

option (google.api.method_signature) = "upload_id";

}

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

rpc GetObject(GetObjectRequest) returns (Object) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket,object";

option (google.api.method_signature) = "bucket,object,generation";

}

// Retrieves object data.

//

// **IAM Permissions**:

//

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

rpc ReadObject(ReadObjectRequest) returns (stream ReadObjectResponse) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "bucket,object";

option (google.api.method_signature) = "bucket,object,generation";

}

// 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 `BidiReadObjectError` proto in its `details` field,

// reporting the specific error, if any, for each pending `read_id`.

//

// **IAM Permissions**:

//

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

//

rpc BidiReadObject(stream BidiReadObjectRequest)

returns (stream BidiReadObjectResponse) {

option (google.api.routing) = {

routing_parameters {

field: "read_object_spec.bucket"

path_template: "{bucket=**}"

}

};

}

// Updates an object's metadata.

// Equivalent to JSON API's `storage.objects.patch` method.

//

// **IAM Permissions**:

//

// Requires `storage.objects.update` IAM permission on the bucket.

rpc UpdateObject(UpdateObjectRequest) returns (Object) {

option (google.api.routing) = {

routing_parameters { field: "object.bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "object,update_mask";

}

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

rpc WriteObject(stream WriteObjectRequest) returns (WriteObjectResponse) {}

// 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 might 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 responds with a `BidiWriteObjectResponse` that contains the

// persisted size. If both `flush` and `state_lookup` are specified, the flush

// always occurs before a `state_lookup`, so that both might 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`

// is always sent to the client, regardless of the value of `state_lookup`.

rpc BidiWriteObject(stream BidiWriteObjectRequest)

returns (stream BidiWriteObjectResponse) {}

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

rpc ListObjects(ListObjectsRequest) returns (ListObjectsResponse) {

option (google.api.routing) = {

routing_parameters { field: "parent" path_template: "{bucket=**}" }

};

option (google.api.method_signature) = "parent";

}

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

// metadata.

rpc RewriteObject(RewriteObjectRequest) returns (RewriteResponse) {

option (google.api.routing) = {

routing_parameters { field: "source_bucket" }

routing_parameters {

field: "destination_bucket"

path_template: "{bucket=**}"

}

};

}

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

rpc StartResumableWrite(StartResumableWriteRequest)

returns (StartResumableWriteResponse) {

option (google.api.routing) = {

routing_parameters {

field: "write_object_spec.resource.bucket"

path_template: "{bucket=**}"

}

};

}

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

rpc QueryWriteStatus(QueryWriteStatusRequest)

returns (QueryWriteStatusResponse) {

option (google.api.routing) = {

routing_parameters {

field: "upload_id"

path_template: "{bucket=projects/*/buckets/*}/**"

}

};

option (google.api.method_signature) = "upload_id";

}

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

rpc MoveObject(MoveObjectRequest) returns (Object) {

option (google.api.routing) = {

routing_parameters { field: "bucket" path_template: "{bucket=**}" }

};

option (google.api.method_signature) =

"bucket,source_object,destination_object";

}

}

// Request message for [DeleteBucket][google.storage.v2.Storage.DeleteBucket].

message DeleteBucketRequest {

// Required. Name of a bucket to delete.

string name = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }

];

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

optional int64 if_metageneration_match = 2;

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

// value.

optional int64 if_metageneration_not_match = 3;

}

// Request message for [GetBucket][google.storage.v2.Storage.GetBucket].

message GetBucketRequest {

// Required. Name of a bucket.

string name = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }

];

// If set, only gets the bucket metadata if its metageneration matches this

// value.

optional int64 if_metageneration_match = 2;

// If set, and if the bucket's current metageneration matches the specified

// value, the request returns an error.

optional int64 if_metageneration_not_match = 3;

// Mask specifying which fields to read.

// A `*` field might be used to indicate all fields.

// If no mask is specified, it defaults to all fields.

optional google.protobuf.FieldMask read_mask = 5;

}

// Request message for [CreateBucket][google.storage.v2.Storage.CreateBucket].

message CreateBucketRequest {

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

string parent = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = {

child_type: "storage.googleapis.com/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 bucket = 2 [(google.api.field_behavior) = OPTIONAL];

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

string bucket_id = 3 [(google.api.field_behavior) = REQUIRED];

// Optional. Apply a predefined set of access controls to this bucket.

// Valid values are `authenticatedRead`, `private`, `projectPrivate`,

// `publicRead`, or `publicReadWrite`.

string predefined_acl = 6 [(google.api.field_behavior) = OPTIONAL];

// Optional. Apply a predefined set of default object access controls to this

// bucket. Valid values are `authenticatedRead`, `bucketOwnerFullControl`,

// `bucketOwnerRead`, `private`, `projectPrivate`, or `publicRead`.

string predefined_default_object_acl = 7

[(google.api.field_behavior) = OPTIONAL];

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

bool enable_object_retention = 9 [(google.api.field_behavior) = OPTIONAL];

}

// Request message for [ListBuckets][google.storage.v2.Storage.ListBuckets].

message ListBucketsRequest {

// Required. The project whose buckets we are listing.

string parent = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = {

child_type: "storage.googleapis.com/Bucket"

}

];

// Optional. Maximum number of buckets to return in a single response. The

// service uses this parameter or `1,000` items, whichever is smaller. If

// `acl` is present in the `read_mask`, the service uses this parameter of

// `200` items, whichever is smaller.

int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

// Optional. A previously-returned page token representing part of the larger

// set of results to view.

string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

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

string prefix = 4 [(google.api.field_behavior) = OPTIONAL];

// Mask specifying which fields to read from each result.

// If no mask is specified, it defaults to all fields except `items.

// owner`, `items.acl`, and `items.default_object_acl`.

// `*` might be used to mean "all fields".

optional google.protobuf.FieldMask read_mask = 5;

// Optional. Allows listing of buckets, even if there are buckets that are

// unreachable.

bool return_partial_success = 9 [(google.api.field_behavior) = OPTIONAL];

}

// Response message for [ListBuckets][google.storage.v2.Storage.ListBuckets].

message ListBucketsResponse {

// The list of items.

repeated Bucket buckets = 1;

// The continuation token, used to page through large result sets. Provide

// this value in a subsequent request to return the next page of results.

string next_page_token = 2;

// Unreachable resources.

// This field can only be present if the caller specified

// return_partial_success to be true in the request to receive indications

// of temporarily missing resources.

// unreachable might be:

// unreachable = [

// "projects/_/buckets/bucket1",

// "projects/_/buckets/bucket2",

// "projects/_/buckets/bucket3",

// ]

repeated string unreachable = 3;

}

// Request message for

// [LockBucketRetentionPolicy][google.storage.v2.Storage.LockBucketRetentionPolicy].

message LockBucketRetentionPolicyRequest {

// Required. Name of a bucket.

string bucket = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }

];

// Required. Makes the operation conditional on whether bucket's current

// metageneration matches the given value. Must be positive.

int64 if_metageneration_match = 2 [(google.api.field_behavior) = REQUIRED];

}

// Request for [UpdateBucket][google.storage.v2.Storage.UpdateBucket] method.

message UpdateBucketRequest {

// Required. The bucket to update.

// The bucket's `name` field is used to identify the bucket.

Bucket bucket = 1 [(google.api.field_behavior) = REQUIRED];

// If set, the request modifies the bucket if its metageneration matches this

// value.

optional int64 if_metageneration_match = 2;

// If set, the request modifies the bucket if its metageneration doesn't

// match this value.

optional int64 if_metageneration_not_match = 3;

// Optional. Apply a predefined set of access controls to this bucket.

// Valid values are `authenticatedRead`, `private`, `projectPrivate`,

// `publicRead`, or `publicReadWrite`.

string predefined_acl = 8 [(google.api.field_behavior) = OPTIONAL];

// Optional. Apply a predefined set of default object access controls to this

// bucket. Valid values are `authenticatedRead`, `bucketOwnerFullControl`,

// `bucketOwnerRead`, `private`, `projectPrivate`, or `publicRead`.

string predefined_default_object_acl = 9

[(google.api.field_behavior) = OPTIONAL];

// Required. List of fields to be updated.

//

// To specify ALL fields, equivalent to the JSON API's "update" function,

// specify a single field with the value `*`. Note: not recommended. If a new

// field is introduced at a later time, an older client updating with the `*`

// might accidentally reset the new field's value.

//

// Not specifying any fields is an error.

google.protobuf.FieldMask update_mask = 6

[(google.api.field_behavior) = REQUIRED];

}

// Request message for [ComposeObject][google.storage.v2.Storage.ComposeObject].

message ComposeObjectRequest {

// Description of a source object for a composition request.

message SourceObject {

// Preconditions for a source object of a composition request.

message ObjectPreconditions {

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

optional int64 if_generation_match = 1;

}

// Required. The source object's name. All source objects must reside in the

// same bucket.

string name = 1 [(google.api.field_behavior) = REQUIRED];

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

int64 generation = 2 [(google.api.field_behavior) = OPTIONAL];

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

ObjectPreconditions object_preconditions = 3

[(google.api.field_behavior) = OPTIONAL];

}

// Required. Properties of the resulting object.

Object destination = 1 [(google.api.field_behavior) = REQUIRED];

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

// object.

repeated SourceObject source_objects = 2

[(google.api.field_behavior) = OPTIONAL];

// Optional. Apply a predefined set of access controls to the destination

// object. Valid values are `authenticatedRead`, `bucketOwnerFullControl`,

// `bucketOwnerRead`, `private`, `projectPrivate`, or `publicRead`.

string destination_predefined_acl = 9

[(google.api.field_behavior) = OPTIONAL];

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

optional int64 if_generation_match = 4;

// Makes the operation conditional on whether the object's current

// metageneration matches the given value.

optional int64 if_metageneration_match = 5;

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

string kms_key = 6 [

(google.api.field_behavior) = OPTIONAL,

(google.api.resource_reference) = {

type: "cloudkms.googleapis.com/CryptoKey"

}

];

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

// object.

CommonObjectRequestParams common_object_request_params = 7

[(google.api.field_behavior) = OPTIONAL];

// Optional. The checksums of the complete object. This is validated against

// the combined checksums of the component objects.

ObjectChecksums object_checksums = 10

[(google.api.field_behavior) = OPTIONAL];

// Whether the source objects should be deleted in the compose request.

optional bool delete_source_objects = 11;

}

// Request message for deleting an object.

message DeleteObjectRequest {

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

string bucket = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }

];

// Required. The name of the finalized object to delete.

// Note: If you want to delete an unfinalized resumable upload please use

// `CancelResumableWrite`.

string object = 2 [(google.api.field_behavior) = REQUIRED];

// Optional. If present, permanently deletes a specific revision of this

// object (as opposed to the latest version, the default).

int64 generation = 4 [(google.api.field_behavior) = OPTIONAL];

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

optional int64 if_generation_match = 5;

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

optional int64 if_generation_not_match = 6;

// Makes the operation conditional on whether the object's current

// metageneration matches the given value.

optional int64 if_metageneration_match = 7;

// Makes the operation conditional on whether the object's current

// metageneration does not match the given value.

optional int64 if_metageneration_not_match = 8;

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

// object.

CommonObjectRequestParams common_object_request_params = 10

[(google.api.field_behavior) = OPTIONAL];

}

// Request message for

// [RestoreObject][google.storage.v2.Storage.RestoreObject].

// `bucket`, `object`, and `generation` **must** be set.

message RestoreObjectRequest {

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

string bucket = 1 [

(google.api.field_behavior) = REQUIRED,

(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }

];

// Required. The name of the object to restore.

string object = 2 [(google.api.field_behavior) = REQUIRED];

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

int64 generation = 3 [(google.api.field_behavior) = REQUIRED];

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

string restore_token = 11 [(google.api.field_behavior) = OPTIONAL];

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

optional int64 if_generation_match = 4;

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

optional int64 if_generation_not_match = 5;

// Makes the operation conditional on whether the object's current

// metageneration matches the given value.

optional int64 if_metageneration_match = 6;

// Makes the operation conditional on whether the object's current

// metageneration does not match the given value.

optional int64 if_metageneration_not_match = 7;

// If false or unset, the bucket's default object ACL is used.

// If true, copy the source object's access controls.

// Return an error if bucket has UBLA enabled.

optional bool copy_source_acl = 9;

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

// object.

CommonObjectRequestParams common_object_request_params = 8

[(google.api.field_behavior) = OPTIONAL];

}

// Request message for

// [CancelResumableWrite][google.storage.v2.Storage.CancelResumableWrite].

message CancelResumableWriteRequest {

// Required. The upload_id of the resumable upload to cancel. This should be

// copied from the `upload_id` field of `StartResumableWriteResponse`.

string upload_id = 1 [(google.api.field_behavior) = REQUIRED];

}

// Empty response message for canceling an in-progress resumable upload, is

// extended as needed.

message CancelResumableWriteResponse {}

// Request message for [ReadObject][google.storage.v2.Storage.ReadObject].

message ReadObjectRequest {

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

string bucket = 1 [