Chiebot-Mirror
/
googleapis
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
pull/728/head
Google APIs 3 years ago committed by Copybara-Service
parent 0b24d03e9f
commit 2938d54a00
2 changed files with 241 additions and 35 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      google/storage/v2/BUILD.bazel
  2. 273
      google/storage/v2/storage.proto

1
google/storage/v2/BUILD.bazel
Unescape 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",

273
google/storage/v2/storage.proto
Unescape 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) = {
// 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];

Write Preview
Loading…
Cancel
Save