Skip to content

Commit 844d0f7

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Add routing annotations
feat!: Update CreateBucket spec to state that bucket field is not REQUIRED feat!: Update UpdateBucketRequest to state that bucket and update_mask fields are REQUIRED feat!: Update ReadObjectRequest to state that bucket and object fields are REQUIRED feat!: Update WriteObjectSpec to state that resource field is REQUIRED feat!: Update RewriteObjectRequest to state that destination_name and destination_bucket fields are REQUIRED feat!: Update StartResumableWriteRequest to state that write_object_spec field is REQUIRED feat!: Update UpdateObjectRequest to state that object and update_mask fields are REQUIRED docs: Remove OPTIONAL annotations on fields where the fields aren't required, and to remove proto-optional annotations feat!: Update BucketAccessControl and specs to include new entity_alt field. PiperOrigin-RevId: 477175825
1 parent f163893 commit 844d0f7

File tree

1 file changed

+103
-42
lines changed

1 file changed

+103
-42
lines changed

‎google/storage/v2/storage.proto‎

Lines changed: 103 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -90,11 +90,23 @@ service Storage {
9090

9191
// Creates a new bucket.
9292
rpc CreateBucket(CreateBucketRequest) returns (Bucket) {
93+
option (google.api.routing) = {
94+
routing_parameters {
95+
field: "parent"
96+
path_template: "{project=**}"
97+
}
98+
};
9399
option (google.api.method_signature) = "parent,bucket,bucket_id";
94100
}
95101

96102
// Retrieves a list of buckets for a given project.
97103
rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse) {
104+
option (google.api.routing) = {
105+
routing_parameters {
106+
field: "parent"
107+
path_template: "{project=**}"
108+
}
109+
};
98110
option (google.api.method_signature) = "parent";
99111
}
100112

@@ -411,31 +423,62 @@ service Storage {
411423

412424
// Retrieves the name of a project's Google Cloud Storage service account.
413425
rpc GetServiceAccount(GetServiceAccountRequest) returns (ServiceAccount) {
426+
option (google.api.routing) = {
427+
routing_parameters {
428+
field: "project"
429+
}
430+
};
414431
option (google.api.method_signature) = "project";
415432
}
416433

417434
// Creates a new HMAC key for the given service account.
418435
rpc CreateHmacKey(CreateHmacKeyRequest) returns (CreateHmacKeyResponse) {
436+
option (google.api.routing) = {
437+
routing_parameters {
438+
field: "project"
439+
}
440+
};
419441
option (google.api.method_signature) = "project,service_account_email";
420442
}
421443

422444
// Deletes a given HMAC key. Key must be in an INACTIVE state.
423445
rpc DeleteHmacKey(DeleteHmacKeyRequest) returns (google.protobuf.Empty) {
446+
option (google.api.routing) = {
447+
routing_parameters {
448+
field: "project"
449+
}
450+
};
424451
option (google.api.method_signature) = "access_id,project";
425452
}
426453

427454
// Gets an existing HMAC key metadata for the given id.
428455
rpc GetHmacKey(GetHmacKeyRequest) returns (HmacKeyMetadata) {
456+
option (google.api.routing) = {
457+
routing_parameters {
458+
field: "project"
459+
}
460+
};
429461
option (google.api.method_signature) = "access_id,project";
430462
}
431463

432464
// Lists HMAC keys under a given project with the additional filters provided.
433465
rpc ListHmacKeys(ListHmacKeysRequest) returns (ListHmacKeysResponse) {
466+
option (google.api.routing) = {
467+
routing_parameters {
468+
field: "project"
469+
}
470+
};
434471
option (google.api.method_signature) = "project";
435472
}
436473

437474
// Updates a given HMAC key state between ACTIVE and INACTIVE.
438475
rpc UpdateHmacKey(UpdateHmacKeyRequest) returns (HmacKeyMetadata) {
476+
option (google.api.routing) = {
477+
routing_parameters {
478+
field: "hmac_key.project"
479+
path_template: "{project=**}"
480+
}
481+
};
439482
option (google.api.method_signature) = "hmac_key,update_mask";
440483
}
441484
}
@@ -492,11 +535,11 @@ message CreateBucketRequest {
492535
}
493536
];
494537

495-
// Required. Properties of the new bucket being inserted.
538+
// Properties of the new bucket being inserted.
496539
// The project and name of the bucket are specified in the parent and
497540
// bucket_id fields, respectively. Populating those fields in `bucket` will
498541
// result in an error.
499-
Bucket bucket = 2 [(google.api.field_behavior) = REQUIRED];
542+
Bucket bucket = 2;
500543

501544
// Required. The ID to use for this bucket, which will become the final component of
502545
// the bucket's resource name. For example, the value `foo` might result in
@@ -564,16 +607,16 @@ message LockBucketRetentionPolicyRequest {
564607
}
565608
];
566609

567-
// Makes the operation conditional on whether bucket's current metageneration
610+
// Required. Makes the operation conditional on whether bucket's current metageneration
568611
// matches the given value. Must be positive.
569-
int64 if_metageneration_match = 2;
612+
int64 if_metageneration_match = 2 [(google.api.field_behavior) = REQUIRED];
570613
}
571614

572615
// Request for UpdateBucket method.
573616
message UpdateBucketRequest {
574-
// The bucket to update.
617+
// Required. The bucket to update.
575618
// The bucket's `name` field will be used to identify the bucket.
576-
Bucket bucket = 1;
619+
Bucket bucket = 1 [(google.api.field_behavior) = REQUIRED];
577620

578621
// If set, will only modify the bucket if its metageneration matches this
579622
// value.
@@ -593,7 +636,7 @@ message UpdateBucketRequest {
593636
// "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
594637
string predefined_default_object_acl = 9;
595638

596-
// List of fields to be updated.
639+
// Required. List of fields to be updated.
597640
//
598641
// To specify ALL fields, equivalent to the JSON API's "update" function,
599642
// specify a single field with the value `*`. Note: not recommended. If a new
@@ -603,7 +646,7 @@ message UpdateBucketRequest {
603646
// Not specifying any fields is an error.
604647
// Not specifying a field while setting that field to a non-default value is
605648
// an error.
606-
google.protobuf.FieldMask update_mask = 6;
649+
google.protobuf.FieldMask update_mask = 6 [(google.api.field_behavior) = REQUIRED];
607650
}
608651

609652
// Request message for DeleteNotification.
@@ -785,11 +828,11 @@ message CancelResumableWriteResponse {
785828

786829
// Request message for ReadObject.
787830
message ReadObjectRequest {
788-
// The name of the bucket containing the object to read.
789-
string bucket = 1;
831+
// Required. The name of the bucket containing the object to read.
832+
string bucket = 1 [(google.api.field_behavior) = REQUIRED];
790833

791-
// The name of the object to read.
792-
string object = 2;
834+
// Required. The name of the object to read.
835+
string object = 2 [(google.api.field_behavior) = REQUIRED];
793836

794837
// If present, selects a specific revision of this object (as opposed
795838
// to the latest version, the default).
@@ -911,8 +954,8 @@ message ReadObjectResponse {
911954

912955
// Describes an attempt to insert an object, possibly over multiple requests.
913956
message WriteObjectSpec {
914-
// Destination object, including its name and its metadata.
915-
Object resource = 1;
957+
// Required. Destination object, including its name and its metadata.
958+
Object resource = 1 [(google.api.field_behavior) = REQUIRED];
916959

917960
// Apply a predefined set of access controls to this object.
918961
// Valid values are "authenticatedRead", "bucketOwnerFullControl",
@@ -1113,17 +1156,21 @@ message QueryWriteStatusResponse {
11131156
// encryption_key_sha256_bytes fields of the
11141157
// common_object_request_params.customer_encryption field.
11151158
message RewriteObjectRequest {
1116-
// Immutable. The name of the destination object.
1159+
// Required. Immutable. The name of the destination object.
11171160
// See the
11181161
// [Naming Guidelines](https://cloud.google.com/storage/docs/naming-objects).
11191162
// Example: `test.txt`
11201163
// The `name` field by itself does not uniquely identify a Cloud Storage
11211164
// object. A Cloud Storage object is uniquely identified by the tuple of
11221165
// (bucket, object, generation).
1123-
string destination_name = 24 [(google.api.field_behavior) = IMMUTABLE];
1166+
string destination_name = 24 [
1167+
(google.api.field_behavior) = REQUIRED,
1168+
(google.api.field_behavior) = IMMUTABLE
1169+
];
11241170

1125-
// Immutable. The name of the bucket containing the destination object.
1171+
// Required. Immutable. The name of the bucket containing the destination object.
11261172
string destination_bucket = 25 [
1173+
(google.api.field_behavior) = REQUIRED,
11271174
(google.api.field_behavior) = IMMUTABLE,
11281175
(google.api.resource_reference) = {
11291176
type: "storage.googleapis.com/Bucket"
@@ -1258,8 +1305,8 @@ message RewriteResponse {
12581305

12591306
// Request message StartResumableWrite.
12601307
message StartResumableWriteRequest {
1261-
// The destination bucket, object, and metadata, as well as any preconditions.
1262-
WriteObjectSpec write_object_spec = 1;
1308+
// Required. The destination bucket, object, and metadata, as well as any preconditions.
1309+
WriteObjectSpec write_object_spec = 1 [(google.api.field_behavior) = REQUIRED];
12631310

12641311
// A set of parameters common to Storage API requests concerning an object.
12651312
CommonObjectRequestParams common_object_request_params = 3;
@@ -1274,12 +1321,12 @@ message StartResumableWriteResponse {
12741321

12751322
// Request message for UpdateObject.
12761323
message UpdateObjectRequest {
1277-
// The object to update.
1324+
// Required. The object to update.
12781325
// The object's bucket and name fields are used to identify the object to
12791326
// update. If present, the object's generation field selects a specific
12801327
// revision of this object whose metadata should be updated. Otherwise,
12811328
// assumes the live version of the object.
1282-
Object object = 1;
1329+
Object object = 1 [(google.api.field_behavior) = REQUIRED];
12831330

12841331
// Makes the operation conditional on whether the object's current generation
12851332
// matches the given value. Setting to 0 makes the operation succeed only if
@@ -1305,7 +1352,7 @@ message UpdateObjectRequest {
13051352
// "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
13061353
string predefined_acl = 10;
13071354

1308-
// List of fields to be updated.
1355+
// Required. List of fields to be updated.
13091356
//
13101357
// To specify ALL fields, equivalent to the JSON API's "update" function,
13111358
// specify a single field with the value `*`. Note: not recommended. If a new
@@ -1315,7 +1362,7 @@ message UpdateObjectRequest {
13151362
// Not specifying any fields is an error.
13161363
// Not specifying a field while setting that field to a non-default value is
13171364
// an error.
1318-
google.protobuf.FieldMask update_mask = 7;
1365+
google.protobuf.FieldMask update_mask = 7 [(google.api.field_behavior) = REQUIRED];
13191366

13201367
// A set of parameters common to Storage API requests concerning an object.
13211368
CommonObjectRequestParams common_object_request_params = 8;
@@ -1403,17 +1450,17 @@ message ListHmacKeysRequest {
14031450
}
14041451
];
14051452

1406-
// Optional. The maximum number of keys to return.
1407-
int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
1453+
// The maximum number of keys to return.
1454+
int32 page_size = 2;
14081455

1409-
// Optional. A previously returned token from ListHmacKeysResponse to get the next page.
1410-
string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
1456+
// A previously returned token from ListHmacKeysResponse to get the next page.
1457+
string page_token = 3;
14111458

1412-
// Optional. If set, filters to only return HMAC keys for specified service account.
1413-
string service_account_email = 4 [(google.api.field_behavior) = OPTIONAL];
1459+
// If set, filters to only return HMAC keys for specified service account.
1460+
string service_account_email = 4;
14141461

1415-
// Optional. If set, return deleted keys that have not yet been wiped out.
1416-
bool show_deleted_keys = 5 [(google.api.field_behavior) = OPTIONAL];
1462+
// If set, return deleted keys that have not yet been wiped out.
1463+
bool show_deleted_keys = 5;
14171464
}
14181465

14191466
// Hmac key list response with next page information.
@@ -1723,7 +1770,7 @@ message Bucket {
17231770
// duration must be greater than zero and less than 100 years. Note that
17241771
// enforcement of retention periods less than a day is not guaranteed. Such
17251772
// periods should only be used for testing purposes.
1726-
int64 retention_period = 3;
1773+
optional int64 retention_period = 3;
17271774
}
17281775

17291776
// Properties of a bucket related to versioning.
@@ -1912,8 +1959,8 @@ message Bucket {
19121959
// Reserved for future use.
19131960
bool satisfies_pzs = 25;
19141961

1915-
// Configuration that, if present, specifies the data placement for a Custom
1916-
// Dual Region.
1962+
// Configuration that, if present, specifies the data placement for a
1963+
// [https://cloud.google.com/storage/docs/use-dual-regions][Dual Region].
19171964
CustomPlacementConfig custom_placement_config = 26;
19181965

19191966
// The bucket's Autoclass configuration. If there is no configuration, the
@@ -1935,7 +1982,8 @@ message BucketAccessControl {
19351982
// * `group-{groupid}`
19361983
// * `group-{email}`
19371984
// * `domain-{domain}`
1938-
// * `project-{team-projectid}`
1985+
// * `project-{team}-{projectnumber}`
1986+
// * `project-{team}-{projectid}`
19391987
// * `allUsers`
19401988
// * `allAuthenticatedUsers`
19411989
// Examples:
@@ -1944,8 +1992,14 @@ message BucketAccessControl {
19441992
// `group-example@googlegroups.com`
19451993
// * All members of the Google Apps for Business domain `example.com` would be
19461994
// `domain-example.com`
1995+
// For project entities, `project-{team}-{projectnumber}` format will be
1996+
// returned on response.
19471997
string entity = 3;
19481998

1999+
// Output only. The alternative entity format, if exists. For project entities,
2000+
// `project-{team}-{projectid}` format will be returned on response.
2001+
string entity_alt = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
2002+
19492003
// The ID for the entity, if any.
19502004
string entity_id = 4;
19512005

@@ -2052,17 +2106,17 @@ message Notification {
20522106
// only be performed if the etag matches that of the Notification.
20532107
string etag = 7;
20542108

2055-
// Optional. If present, only send notifications about listed event types. If empty,
2109+
// If present, only send notifications about listed event types. If empty,
20562110
// sent notifications for all event types.
2057-
repeated string event_types = 3 [(google.api.field_behavior) = OPTIONAL];
2111+
repeated string event_types = 3;
20582112

2059-
// Optional. An optional list of additional attributes to attach to each Pub/Sub
2113+
// A list of additional attributes to attach to each Pub/Sub
20602114
// message published for this notification subscription.
2061-
map<string, string> custom_attributes = 4 [(google.api.field_behavior) = OPTIONAL];
2115+
map<string, string> custom_attributes = 4;
20622116

2063-
// Optional. If present, only apply this notification config to object names that
2117+
// If present, only apply this notification config to object names that
20642118
// begin with this prefix.
2065-
string object_name_prefix = 5 [(google.api.field_behavior) = OPTIONAL];
2119+
string object_name_prefix = 5;
20662120

20672121
// Required. The desired content of the Payload.
20682122
string payload_format = 6 [(google.api.field_behavior) = REQUIRED];
@@ -2256,7 +2310,8 @@ message ObjectAccessControl {
22562310
// * `group-{groupid}`
22572311
// * `group-{email}`
22582312
// * `domain-{domain}`
2259-
// * `project-{team-projectid}`
2313+
// * `project-{team}-{projectnumber}`
2314+
// * `project-{team}-{projectid}`
22602315
// * `allUsers`
22612316
// * `allAuthenticatedUsers`
22622317
// Examples:
@@ -2265,8 +2320,14 @@ message ObjectAccessControl {
22652320
// `group-example@googlegroups.com`.
22662321
// * All members of the Google Apps for Business domain `example.com` would be
22672322
// `domain-example.com`.
2323+
// For project entities, `project-{team}-{projectnumber}` format will be
2324+
// returned on response.
22682325
string entity = 3;
22692326

2327+
// Output only. The alternative entity format, if exists. For project entities,
2328+
// `project-{team}-{projectid}` format will be returned on response.
2329+
string entity_alt = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
2330+
22702331
// The ID for the entity, if any.
22712332
string entity_id = 4;
22722333

0 commit comments

Comments
 (0)