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

google/storage/v2/storage.proto

@@ -90,11 +90,23 @@ service Storage {
 
   // Creates a new bucket.
   rpc CreateBucket(CreateBucketRequest) returns (Bucket) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{project=**}"
+      }
+    };
     option (google.api.method_signature) = "parent,bucket,bucket_id";
   }
 
   // Retrieves a list of buckets for a given project.
   rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{project=**}"
+      }
+    };
     option (google.api.method_signature) = "parent";
   }
 
@@ -411,31 +423,62 @@ service Storage {
 
   // Retrieves the name of a project's Google Cloud Storage service account.
   rpc GetServiceAccount(GetServiceAccountRequest) returns (ServiceAccount) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "project"
+      }
+    };
     option (google.api.method_signature) = "project";
   }
 
   // Creates a new HMAC key for the given service account.
   rpc CreateHmacKey(CreateHmacKeyRequest) returns (CreateHmacKeyResponse) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "project"
+      }
+    };
     option (google.api.method_signature) = "project,service_account_email";
   }
 
   // Deletes a given HMAC key.  Key must be in an INACTIVE state.
   rpc DeleteHmacKey(DeleteHmacKeyRequest) returns (google.protobuf.Empty) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "project"
+      }
+    };
     option (google.api.method_signature) = "access_id,project";
   }
 
   // Gets an existing HMAC key metadata for the given id.
   rpc GetHmacKey(GetHmacKeyRequest) returns (HmacKeyMetadata) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "project"
+      }
+    };
     option (google.api.method_signature) = "access_id,project";
   }
 
   // Lists HMAC keys under a given project with the additional filters provided.
   rpc ListHmacKeys(ListHmacKeysRequest) returns (ListHmacKeysResponse) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "project"
+      }
+    };
     option (google.api.method_signature) = "project";
   }
 
   // Updates a given HMAC key state between ACTIVE and INACTIVE.
   rpc UpdateHmacKey(UpdateHmacKeyRequest) returns (HmacKeyMetadata) {
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "hmac_key.project"
+        path_template: "{project=**}"
+      }
+    };
     option (google.api.method_signature) = "hmac_key,update_mask";
   }
 }
@@ -492,11 +535,11 @@ message CreateBucketRequest {
     }
   ];
 
-  // Required. Properties of the new bucket being inserted.
+  // Properties of the new bucket being inserted.
   // The project and name of the bucket are specified in the parent and
   // bucket_id fields, respectively. Populating those fields in `bucket` will
   // result in an error.
-  Bucket bucket = 2 [(google.api.field_behavior) = REQUIRED];
+  Bucket bucket = 2;
 
   // Required. The ID to use for this bucket, which will become the final component of
   // the bucket's resource name. For example, the value `foo` might result in
@@ -564,16 +607,16 @@ message LockBucketRetentionPolicyRequest {
     }
   ];
 
-  // Makes the operation conditional on whether bucket's current metageneration
+  // Required. Makes the operation conditional on whether bucket's current metageneration
   // matches the given value. Must be positive.
-  int64 if_metageneration_match = 2;
+  int64 if_metageneration_match = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
 // Request for UpdateBucket method.
 message UpdateBucketRequest {
-  // The bucket to update.
+  // Required. The bucket to update.
   // The bucket's `name` field will be used to identify the bucket.
-  Bucket bucket = 1;
+  Bucket bucket = 1 [(google.api.field_behavior) = REQUIRED];
 
   // If set, will only modify the bucket if its metageneration matches this
   // value.
@@ -593,7 +636,7 @@ message UpdateBucketRequest {
   // "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
   string predefined_default_object_acl = 9;
 
-  // List of fields to be updated.
+  // 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
@@ -603,7 +646,7 @@ message UpdateBucketRequest {
   // Not specifying any fields is an error.
   // Not specifying a field while setting that field to a non-default value is
   // an error.
-  google.protobuf.FieldMask update_mask = 6;
+  google.protobuf.FieldMask update_mask = 6 [(google.api.field_behavior) = REQUIRED];
 }
 
 // Request message for DeleteNotification.
@@ -785,11 +828,11 @@ message CancelResumableWriteResponse {
 
 // Request message for ReadObject.
 message ReadObjectRequest {
-  // The name of the bucket containing the object to read.
-  string bucket = 1;
+  // Required. The name of the bucket containing the object to read.
+  string bucket = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // The name of the object to read.
-  string object = 2;
+  // Required. The name of the object to read.
+  string object = 2 [(google.api.field_behavior) = REQUIRED];
 
   // If present, selects a specific revision of this object (as opposed
   // to the latest version, the default).
@@ -911,8 +954,8 @@ message ReadObjectResponse {
 
 // Describes an attempt to insert an object, possibly over multiple requests.
 message WriteObjectSpec {
-  // Destination object, including its name and its metadata.
-  Object resource = 1;
+  // Required. Destination object, including its name and its metadata.
+  Object resource = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Apply a predefined set of access controls to this object.
   // Valid values are "authenticatedRead", "bucketOwnerFullControl",
@@ -1113,17 +1156,21 @@ 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.
+  // Required. 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];
+  string destination_name = 24 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
 
-  // Immutable. The name of the bucket containing the destination object.
+  // Required. Immutable. The name of the bucket containing the destination object.
   string destination_bucket = 25 [
+    (google.api.field_behavior) = REQUIRED,
     (google.api.field_behavior) = IMMUTABLE,
     (google.api.resource_reference) = {
       type: "storage.googleapis.com/Bucket"
@@ -1258,8 +1305,8 @@ message RewriteResponse {
 
 // Request message StartResumableWrite.
 message StartResumableWriteRequest {
-  // The destination bucket, object, and metadata, as well as any preconditions.
-  WriteObjectSpec write_object_spec = 1;
+  // Required. The destination bucket, object, and metadata, as well as any preconditions.
+  WriteObjectSpec write_object_spec = 1 [(google.api.field_behavior) = REQUIRED];
 
   // A set of parameters common to Storage API requests concerning an object.
   CommonObjectRequestParams common_object_request_params = 3;
@@ -1274,12 +1321,12 @@ message StartResumableWriteResponse {
 
 // Request message for UpdateObject.
 message UpdateObjectRequest {
-  // The object to update.
+  // Required. The object to update.
   // The object's bucket and name fields are used to identify the object to
   // update. If present, the object's generation field selects a specific
   // revision of this object whose metadata should be updated. Otherwise,
   // assumes the live version of the object.
-  Object object = 1;
+  Object object = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Makes the operation conditional on whether the object's current generation
   // matches the given value. Setting to 0 makes the operation succeed only if
@@ -1305,7 +1352,7 @@ message UpdateObjectRequest {
   // "bucketOwnerRead", "private", "projectPrivate", or "publicRead".
   string predefined_acl = 10;
 
-  // List of fields to be updated.
+  // 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
@@ -1315,7 +1362,7 @@ message UpdateObjectRequest {
   // Not specifying any fields is an error.
   // Not specifying a field while setting that field to a non-default value is
   // an error.
-  google.protobuf.FieldMask update_mask = 7;
+  google.protobuf.FieldMask update_mask = 7 [(google.api.field_behavior) = REQUIRED];
 
   // A set of parameters common to Storage API requests concerning an object.
   CommonObjectRequestParams common_object_request_params = 8;
@@ -1403,17 +1450,17 @@ message ListHmacKeysRequest {
     }
   ];
 
-  // Optional. The maximum number of keys to return.
-  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+  // The maximum number of keys to return.
+  int32 page_size = 2;
 
-  // Optional. A previously returned token from ListHmacKeysResponse to get the next page.
-  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+  // A previously returned token from ListHmacKeysResponse to get the next page.
+  string page_token = 3;
 
-  // Optional. If set, filters to only return HMAC keys for specified service account.
-  string service_account_email = 4 [(google.api.field_behavior) = OPTIONAL];
+  // If set, filters to only return HMAC keys for specified service account.
+  string service_account_email = 4;
 
-  // Optional. If set, return deleted keys that have not yet been wiped out.
-  bool show_deleted_keys = 5 [(google.api.field_behavior) = OPTIONAL];
+  // If set, return deleted keys that have not yet been wiped out.
+  bool show_deleted_keys = 5;
 }
 
 // Hmac key list response with next page information.
@@ -1723,7 +1770,7 @@ message Bucket {
     // duration must be greater than zero and less than 100 years. Note that
     // enforcement of retention periods less than a day is not guaranteed. Such
     // periods should only be used for testing purposes.
-    int64 retention_period = 3;
+    optional int64 retention_period = 3;
   }
 
   // Properties of a bucket related to versioning.
@@ -1912,8 +1959,8 @@ message Bucket {
   // Reserved for future use.
   bool satisfies_pzs = 25;
 
-  // Configuration that, if present, specifies the data placement for a Custom
-  // Dual Region.
+  // Configuration that, if present, specifies the data placement for a
+  // [https://cloud.google.com/storage/docs/use-dual-regions][Dual Region].
   CustomPlacementConfig custom_placement_config = 26;
 
   // The bucket's Autoclass configuration. If there is no configuration, the
@@ -1935,7 +1982,8 @@ message BucketAccessControl {
   // * `group-{groupid}`
   // * `group-{email}`
   // * `domain-{domain}`
-  // * `project-{team-projectid}`
+  // * `project-{team}-{projectnumber}`
+  // * `project-{team}-{projectid}`
   // * `allUsers`
   // * `allAuthenticatedUsers`
   // Examples:
@@ -1944,8 +1992,14 @@ message BucketAccessControl {
   // `[email protected]`
   // * All members of the Google Apps for Business domain `example.com` would be
   // `domain-example.com`
+  // For project entities, `project-{team}-{projectnumber}` format will be
+  // returned on response.
   string entity = 3;
 
+  // Output only. The alternative entity format, if exists. For project entities,
+  // `project-{team}-{projectid}` format will be returned on response.
+  string entity_alt = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // The ID for the entity, if any.
   string entity_id = 4;
 
@@ -2052,17 +2106,17 @@ message Notification {
   // only be performed if the etag matches that of the Notification.
   string etag = 7;
 
-  // Optional. If present, only send notifications about listed event types. If empty,
+  // If present, only send notifications about listed event types. If empty,
   // sent notifications for all event types.
-  repeated string event_types = 3 [(google.api.field_behavior) = OPTIONAL];
+  repeated string event_types = 3;
 
-  // Optional. An optional list of additional attributes to attach to each Pub/Sub
+  // A list of additional attributes to attach to each Pub/Sub
   // message published for this notification subscription.
-  map<string, string> custom_attributes = 4 [(google.api.field_behavior) = OPTIONAL];
+  map<string, string> custom_attributes = 4;
 
-  // Optional. If present, only apply this notification config to object names that
+  // If present, only apply this notification config to object names that
   // begin with this prefix.
-  string object_name_prefix = 5 [(google.api.field_behavior) = OPTIONAL];
+  string object_name_prefix = 5;
 
   // Required. The desired content of the Payload.
   string payload_format = 6 [(google.api.field_behavior) = REQUIRED];
@@ -2256,7 +2310,8 @@ message ObjectAccessControl {
   // * `group-{groupid}`
   // * `group-{email}`
   // * `domain-{domain}`
-  // * `project-{team-projectid}`
+  // * `project-{team}-{projectnumber}`
+  // * `project-{team}-{projectid}`
   // * `allUsers`
   // * `allAuthenticatedUsers`
   // Examples:
@@ -2265,8 +2320,14 @@ message ObjectAccessControl {
   // `[email protected]`.
   // * All members of the Google Apps for Business domain `example.com` would be
   // `domain-example.com`.
+  // For project entities, `project-{team}-{projectnumber}` format will be
+  // returned on response.
   string entity = 3;
 
+  // Output only. The alternative entity format, if exists. For project entities,
+  // `project-{team}-{projectid}` format will be returned on response.
+  string entity_alt = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // The ID for the entity, if any.
   string entity_id = 4;