diff --git a/google/storage/v2/BUILD.bazel b/google/storage/v2/BUILD.bazel index 4d6ae86d9..09b187f17 100644 --- a/google/storage/v2/BUILD.bazel +++ b/google/storage/v2/BUILD.bazel @@ -27,6 +27,7 @@ proto_library( "//google/api:client_proto", "//google/api:field_behavior_proto", "//google/api:resource_proto", + "//google/api:routing_proto", "//google/iam/v1:iam_policy_proto", "//google/iam/v1:policy_proto", "//google/type:date_proto", diff --git a/google/storage/v2/storage.proto b/google/storage/v2/storage.proto index 4b0fb49aa..577463db5 100644 --- a/google/storage/v2/storage.proto +++ b/google/storage/v2/storage.proto @@ -19,6 +19,7 @@ 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/empty.proto"; @@ -67,11 +68,23 @@ service Storage { // Permanently deletes an empty 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. rpc GetBucket(GetBucketRequest) returns (Bucket) { + option (google.api.routing) = { + routing_parameters { + field: "name" + path_template: "{bucket=**}" + } + }; option (google.api.method_signature) = "name"; } @@ -87,37 +100,91 @@ service Storage { // Locks retention policy on a 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. + // Gets the IAM policy for a specified bucket or object. 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/*}/objects/**" + } + }; option (google.api.method_signature) = "resource"; } - // Updates an IAM policy for the specified bucket. + // Updates an IAM policy for the specified bucket or object. 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/*}/objects/**" + } + }; option (google.api.method_signature) = "resource,policy"; } - // Tests a set of permissions on the given bucket to see which, if + // Tests a set of permissions on the given bucket or object to see which, if // any, are held by the caller. 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/**" + } + }; option (google.api.method_signature) = "resource,permissions"; } // Updates a bucket. Equivalent to JSON API's storage.buckets.patch method. 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"; } // Permanently deletes a notification subscription. rpc DeleteNotification(DeleteNotificationRequest) returns (google.protobuf.Empty) { + option (google.api.routing) = { + routing_parameters { + field: "name" + path_template: "{bucket=projects/*/buckets/*}/**" + } + }; option (google.api.method_signature) = "name"; } // View a notification config. rpc GetNotification(GetNotificationRequest) returns (Notification) { + option (google.api.routing) = { + routing_parameters { + field: "name" + path_template: "{bucket=projects/*/buckets/*}/**" + } + }; option (google.api.method_signature) = "name"; } @@ -126,35 +193,81 @@ service Storage { // Pub/Sub topics. // See https://cloud.google.com/storage/docs/pubsub-notifications. rpc CreateNotification(CreateNotificationRequest) returns (Notification) { + option (google.api.routing) = { + routing_parameters { + field: "parent" + path_template: "{bucket=**}" + } + }; option (google.api.method_signature) = "parent,notification"; } // Retrieves a list of notification subscriptions for a given bucket. rpc ListNotifications(ListNotificationsRequest) returns (ListNotificationsResponse) { + option (google.api.routing) = { + routing_parameters { + field: "parent" + path_template: "{bucket=**}" + } + }; option (google.api.method_signature) = "parent"; } // Concatenates a list of existing objects into a new object in the same // bucket. 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. + // is not enabled for the bucket, or if the `generation` parameter is used. 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"; } + // Cancels an in-progress resumable upload. + 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 an object's metadata. 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"; } // Reads an object's data. 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"; } @@ -162,6 +275,12 @@ service Storage { // Updates an object's metadata. // Equivalent to JSON API's storage.objects.patch. 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"; } @@ -218,22 +337,53 @@ service Storage { // status, with a WriteObjectResponse containing the finalized object's // metadata. rpc WriteObject(stream WriteObjectRequest) returns (WriteObjectResponse) { + option (google.api.routing) = { + routing_parameters { + field: "write_object_spec.resource.bucket" + path_template: "{bucket=**}" + } + routing_parameters { + field: "upload_id" + path_template: "{bucket=projects/*/buckets/*}/**" + } + }; } // Retrieves a list of objects matching the criteria. 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. How long the write operation remains valid, and // what happens when the write operation becomes invalid, are // service-dependent. rpc StartResumableWrite(StartResumableWriteRequest) returns (StartResumableWriteResponse) { + option (google.api.routing) = { + routing_parameters { + field: "write_object_spec.resource.bucket" + path_template: "{bucket=**}" + } + }; } // Determines the `persisted_size` for an object that is being written, which @@ -250,6 +400,12 @@ service Storage { // object name, the sequence of returned `persisted_size` values will be // 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"; } @@ -578,7 +734,7 @@ message ComposeObjectRequest { } // Message for deleting an object. -// Either `bucket` and `object` *or* `upload_id` **must** be set (but not both). +// `bucket` and `object` **must** be set. message DeleteObjectRequest { // Required. Name of the bucket in which the object resides. string bucket = 1 [(google.api.field_behavior) = REQUIRED]; @@ -586,11 +742,6 @@ message DeleteObjectRequest { // Required. The name of the object to delete (when not using a resumable write). string object = 2 [(google.api.field_behavior) = REQUIRED]; - // The resumable upload_id of the object to delete (when deleting an - // in-progress resumable write). This should be copied from the `upload_id` - // field of `StartResumableWriteResponse`. - string upload_id = 3; - // If present, permanently deletes a specific revision of this object (as // opposed to the latest version, the default). int64 generation = 4; @@ -618,6 +769,20 @@ message DeleteObjectRequest { CommonObjectRequestParams common_object_request_params = 10; } +// Message for canceling an in-progress resumable upload. +// `upload_id` **must** be set. +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, will be +// extended as needed. +message CancelResumableWriteResponse { + +} + // Request message for ReadObject. message ReadObjectRequest { // The name of the bucket containing the object to read. @@ -772,6 +937,17 @@ message WriteObjectSpec { // Makes the operation conditional on whether the object's current // metageneration does not match the given value. optional int64 if_metageneration_not_match = 6; + + // 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. + // + // The `object_size` value is ignored for one-shot (non-resumable) writes. + optional int64 object_size = 8; } // Request message for WriteObject. @@ -937,16 +1113,16 @@ message QueryWriteStatusResponse { // encryption_key_sha256_bytes fields of the // common_object_request_params.customer_encryption field. message RewriteObjectRequest { - // Immutable. The name of the destination object. Nearly any sequence of unicode - // characters is valid. See - // [Guidelines](https://cloud.google.com/storage/docs/naming-objects). + // Immutable. The name of the destination object. + // See the + // [Naming Guidelines](https://cloud.google.com/storage/docs/naming-objects). // 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). string destination_name = 24 [(google.api.field_behavior) = IMMUTABLE]; - // Immutable. The name of the bucket containing The name of the destination object. + // Immutable. The name of the bucket containing the destination object. string destination_bucket = 25 [ (google.api.field_behavior) = IMMUTABLE, (google.api.resource_reference) = { @@ -1147,7 +1323,8 @@ message UpdateObjectRequest { // Request message for GetServiceAccount. message GetServiceAccountRequest { - // Required. Project ID. + // Required. Project ID, in the format of "projects/". + // can be the project ID or project number. string project = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -1158,7 +1335,9 @@ message GetServiceAccountRequest { // Request message for CreateHmacKey. message CreateHmacKeyRequest { - // Required. The project that the HMAC-owning service account lives in. + // Required. The project that the HMAC-owning service account lives in, in the format of + // "projects/". + // can be the project ID or project number. string project = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -1185,7 +1364,9 @@ message DeleteHmacKeyRequest { // Required. The identifying key for the HMAC to delete. string access_id = 1 [(google.api.field_behavior) = REQUIRED]; - // Required. The project id the HMAC key lies in. + // Required. The project that owns the HMAC key, in the format of + // "projects/". + // can be the project ID or project number. string project = 2 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -1199,7 +1380,9 @@ message GetHmacKeyRequest { // Required. The identifying key for the HMAC to delete. string access_id = 1 [(google.api.field_behavior) = REQUIRED]; - // Required. The project id the HMAC key lies in. + // Required. The project the HMAC key lies in, in the format of + // "projects/". + // can be the project ID or project number. string project = 2 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -1210,7 +1393,9 @@ message GetHmacKeyRequest { // Request to fetch a list of HMAC keys under a given project. message ListHmacKeysRequest { - // Required. The project id to list HMAC keys for. + // Required. The project to list HMAC keys for, in the format of + // "projects/". + // can be the project ID or project number. string project = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -1242,6 +1427,9 @@ message ListHmacKeysResponse { } // Request object to update an HMAC key state. +// HmacKeyMetadata.state is required and the only writable field in +// UpdateHmacKey operation. Specifying fields other than state will result in an +// error. message UpdateHmacKeyRequest { // Required. The HMAC key to update. // If present, the hmac_key's `id` field will be used to identify the key. @@ -1250,6 +1438,8 @@ message UpdateHmacKeyRequest { HmacKeyMetadata hmac_key = 1 [(google.api.field_behavior) = REQUIRED]; // Update mask for hmac_key. + // Not specifying any fields will mean only the `state` field is updated to + // the value specified in `hmac_key`. google.protobuf.FieldMask update_mask = 3; } @@ -1595,7 +1785,9 @@ message Bucket { // only be performed if the etag matches that of the bucket. string etag = 29; - // Immutable. The project which owns this bucket. + // Immutable. The project which owns this bucket, in the format of + // "projects/". + // can be the project ID or project number. string project = 3 [ (google.api.field_behavior) = IMMUTABLE, (google.api.resource_reference) = { @@ -1803,28 +1995,36 @@ message ObjectChecksums { // Hmac Key Metadata, which includes all information other than the secret. message HmacKeyMetadata { - // Resource name ID of the key in the format /. - string id = 1; + // Immutable. Resource name ID of the key in the format + // /. + // can be the project ID or project number. + string id = 1 [(google.api.field_behavior) = IMMUTABLE]; - // Globally unique id for keys. - string access_id = 2; + // Immutable. Globally unique id for keys. + string access_id = 2 [(google.api.field_behavior) = IMMUTABLE]; - // The project ID that the hmac key is contained in. - string project = 3 [(google.api.resource_reference) = { - type: "cloudresourcemanager.googleapis.com/Project" - }]; + // Immutable. Identifies the project that owns the service account of the specified HMAC + // key, in the format "projects/". can + // be the project ID or project number. + string project = 3 [ + (google.api.field_behavior) = IMMUTABLE, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; - // Email of the service account the key authenticates as. - string service_account_email = 4; + // Output only. Email of the service account the key authenticates as. + string service_account_email = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; // State of the key. One of ACTIVE, INACTIVE, or DELETED. + // Writable, can be updated by UpdateHmacKey operation. string state = 5; - // The creation time of the HMAC key. - google.protobuf.Timestamp create_time = 6; + // Output only. The creation time of the HMAC key. + google.protobuf.Timestamp create_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; - // The last modification time of the HMAC key metadata. - google.protobuf.Timestamp update_time = 7; + // Output only. The last modification time of the HMAC key metadata. + google.protobuf.Timestamp update_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; // The etag of the HMAC key. string etag = 8; @@ -1976,6 +2176,11 @@ message Object { ObjectChecksums checksums = 16 [(google.api.field_behavior) = OUTPUT_ONLY]; // 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. // Attempting to set or update this field will result in a // [FieldViolation][google.rpc.BadRequest.FieldViolation]. google.protobuf.Timestamp update_time = 17 [(google.api.field_behavior) = OUTPUT_ONLY];