GlcoinCore/googleapis
1
0
Fork 0
mirror of https://github.com/googleapis/googleapis.git synced 2026-08-15 12:50:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: Add routing annotations

Browse source 
docs: Clarify that IAM RPCs apply to buckets as well as objects

feat!: Removed upload_id from DeleteObjectRequest, and in its place defined separate CancelResumableWriteRequest RPC

feat: Added optional object_size to WriteObjectSpec, as constraint on object being written

docs: Clarified project ID format of various RPCs

docs: Clarified behavior of update_mask in UpdateHmacKeyRequest

docs: Clarified meaning/behavior of fields in HmacKeyMetadata

docs: Clarified cases where update_time is updated in Bucket message

docs: Clarified UpdateHmacKeyRequest.update_mask behavior

docs: Clarified meaning of <projectIdentifier> for several RPCs
PiperOrigin-RevId: 461979598
This commit is contained in:
Google APIs 2022-07-19 14:41:09 -07:00 • committed by Copybara-Service
parent 0b24d03e9f
commit 2938d54a00
2 changed files with 241 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

1
google/storage/v2/BUILD.bazel
View file

@ -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",

275
google/storage/v2/storage.proto
View file

@ -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/<projectIdentifier>".
// <projectIdentifier> 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/<projectIdentifier>".
// <projectIdentifier> 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/<projectIdentifier>".
// <projectIdentifier> 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/<projectIdentifier>".
// <projectIdentifier> 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/<projectIdentifier>".
// <projectIdentifier> 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/<projectIdentifier>".
// <projectIdentifier> 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 <projectId>/<accessId>.
string id = 1;
// Immutable. Resource name ID of the key in the format
// <projectIdentifier>/<accessId>.
// <projectIdentifier> 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/<projectIdentifier>". <projectIdentifier> 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];