feat: [common-protos] add api_version extension to ServiceOptions…

…, for collaborative versioning (#2551)

- [ ] Regenerate this pull request now.

feat: add `Publishing.rest_reference_documentation_uri` to aid client library publication
feat: add `ErrorReason.LOCATION_POLICY_VIOLATED` enum value
docs: minor tweaks to various comments

PiperOrigin-RevId: 613949885

Source-Link: https://togithub.com/googleapis/googleapis/commit/dba3883bfb9207b943e07a7efef1327939628926

Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/71e160a4138c85961a25c6ac9d013b0c7f2d7266
Copy-Tag: eyJwIjoiamF2YS1jb21tb24tcHJvdG9zLy5Pd2xCb3QueWFtbCIsImgiOiI3MWUxNjBhNDEzOGM4NTk2MWEyNWM2YWM5ZDAxM2IwYzdmMmQ3MjY2In0=

BEGIN_NESTED_COMMIT
feat: [common-protos] add `api_version` extension to `ServiceOptions`, for collaborative versioning
feat: add `Publishing.rest_reference_documentation_uri` to aid client library publication
feat: add `ErrorReason.LOCATION_POLICY_VIOLATED` enum value
docs: minor tweaks to various comments

PiperOrigin-RevId: 613949885

Source-Link: https://togithub.com/googleapis/googleapis/commit/dba3883bfb9207b943e07a7efef1327939628926

Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/71e160a4138c85961a25c6ac9d013b0c7f2d7266
Copy-Tag: eyJwIjoiamF2YS1jb21tb24tcHJvdG9zLy5Pd2xCb3QueWFtbCIsImgiOiI3MWUxNjBhNDEzOGM4NTk2MWEyNWM2YWM5ZDAxM2IwYzdmMmQ3MjY2In0=
END_NESTED_COMMIT

java-common-protos/README.md

@@ -19,20 +19,20 @@ If you are using Maven, add this to your pom.xml file:
 <dependency>
   <groupId>com.google.api.grpc</groupId>
   <artifactId>proto-google-common-protos</artifactId>
-  <version>2.33.0</version>
+  <version>2.36.0</version>
 </dependency>
 ```
 
 If you are using Gradle without BOM, add this to your dependencies:
 
 ```Groovy
-implementation 'com.google.api.grpc:proto-google-common-protos:2.33.0'
+implementation 'com.google.api.grpc:proto-google-common-protos:2.36.0'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.api.grpc" % "proto-google-common-protos" % "2.33.0"
+libraryDependencies += "com.google.api.grpc" % "proto-google-common-protos" % "2.36.0"
 ```
 
 ## Authentication

java-common-protos/proto-google-common-protos/src/main/java/com/google/api/ClientProto.java

@@ -26,6 +26,7 @@ public static void registerAllExtensions(com.google.protobuf.ExtensionRegistryLi
     registry.add(com.google.api.ClientProto.methodSignature);
     registry.add(com.google.api.ClientProto.defaultHost);
     registry.add(com.google.api.ClientProto.oauthScopes);
+    registry.add(com.google.api.ClientProto.apiVersion);
   }
 
   public static void registerAllExtensions(com.google.protobuf.ExtensionRegistry registry) {
@@ -141,6 +142,35 @@ public static void registerAllExtensions(com.google.protobuf.ExtensionRegistry r
           com.google.protobuf.GeneratedMessage.newFileScopedGeneratedExtension(
               java.lang.String.class, null);
 
+  public static final int API_VERSION_FIELD_NUMBER = 525000001;
+  /**
+   *
+   *
+   * <pre>
+   * The API version of this service, which should be sent by version-aware
+   * clients to the service. This allows services to abide by the schema and
+   * behavior of the service at the time this API version was deployed.
+   * The format of the API version must be treated as opaque by clients.
+   * Services may use a format with an apparent structure, but clients must
+   * not rely on this to determine components within an API version, or attempt
+   * to construct other valid API versions. Note that this is for upcoming
+   * functionality and may not be implemented for all services.
+   *
+   * Example:
+   *
+   *   service Foo {
+   *     option (google.api.api_version) = "v1_20230821_preview";
+   *   }
+   * </pre>
+   *
+   * <code>extend .google.protobuf.ServiceOptions { ... }</code>
+   */
+  public static final com.google.protobuf.GeneratedMessage.GeneratedExtension<
+          com.google.protobuf.DescriptorProtos.ServiceOptions, java.lang.String>
+      apiVersion =
+          com.google.protobuf.GeneratedMessage.newFileScopedGeneratedExtension(
+              java.lang.String.class, null);
+
   static final com.google.protobuf.Descriptors.Descriptor
       internal_static_google_api_CommonLanguageSettings_descriptor;
   static final com.google.protobuf.GeneratedMessageV3.FieldAccessorTable
@@ -233,7 +263,7 @@ public static com.google.protobuf.Descriptors.FileDescriptor getDescriptor() {
           + "2\032.google.api.DotnetSettings\022/\n\rruby_set"
           + "tings\030\033 \001(\0132\030.google.api.RubySettings\022+\n"
           + "\013go_settings\030\034 \001(\0132\026.google.api.GoSettin"
-          + "gs\"\376\002\n\nPublishing\0223\n\017method_settings\030\002 \003"
+          + "gs\"\250\003\n\nPublishing\0223\n\017method_settings\030\002 \003"
           + "(\0132\032.google.api.MethodSettings\022\025\n\rnew_is"
           + "sue_uri\030e \001(\t\022\031\n\021documentation_uri\030f \001(\t"
           + "\022\026\n\016api_short_name\030g \001(\t\022\024\n\014github_label"
@@ -242,56 +272,59 @@ public static com.google.protobuf.Descriptors.FileDescriptor getDescriptor() {
           + " \001(\0162%.google.api.ClientLibraryOrganizat"
           + "ion\022;\n\020library_settings\030m \003(\0132!.google.a"
           + "pi.ClientLibrarySettings\022)\n!proto_refere"
-          + "nce_documentation_uri\030n \001(\t\"\343\001\n\014JavaSett"
-          + "ings\022\027\n\017library_package\030\001 \001(\t\022L\n\023service"
-          + "_class_names\030\002 \003(\0132/.google.api.JavaSett"
-          + "ings.ServiceClassNamesEntry\0222\n\006common\030\003 "
-          + "\001(\0132\".google.api.CommonLanguageSettings\032"
-          + "8\n\026ServiceClassNamesEntry\022\013\n\003key\030\001 \001(\t\022\r"
-          + "\n\005value\030\002 \001(\t:\0028\001\"A\n\013CppSettings\0222\n\006comm"
-          + "on\030\001 \001(\0132\".google.api.CommonLanguageSett"
-          + "ings\"A\n\013PhpSettings\0222\n\006common\030\001 \001(\0132\".go"
-          + "ogle.api.CommonLanguageSettings\"D\n\016Pytho"
-          + "nSettings\0222\n\006common\030\001 \001(\0132\".google.api.C"
-          + "ommonLanguageSettings\"B\n\014NodeSettings\0222\n"
-          + "\006common\030\001 \001(\0132\".google.api.CommonLanguag"
-          + "eSettings\"\252\003\n\016DotnetSettings\0222\n\006common\030\001"
-          + " \001(\0132\".google.api.CommonLanguageSettings"
-          + "\022I\n\020renamed_services\030\002 \003(\0132/.google.api."
-          + "DotnetSettings.RenamedServicesEntry\022K\n\021r"
-          + "enamed_resources\030\003 \003(\01320.google.api.Dotn"
-          + "etSettings.RenamedResourcesEntry\022\031\n\021igno"
-          + "red_resources\030\004 \003(\t\022 \n\030forced_namespace_"
-          + "aliases\030\005 \003(\t\022\036\n\026handwritten_signatures\030"
-          + "\006 \003(\t\0326\n\024RenamedServicesEntry\022\013\n\003key\030\001 \001"
-          + "(\t\022\r\n\005value\030\002 \001(\t:\0028\001\0327\n\025RenamedResource"
-          + "sEntry\022\013\n\003key\030\001 \001(\t\022\r\n\005value\030\002 \001(\t:\0028\001\"B"
-          + "\n\014RubySettings\0222\n\006common\030\001 \001(\0132\".google."
-          + "api.CommonLanguageSettings\"@\n\nGoSettings"
-          + "\0222\n\006common\030\001 \001(\0132\".google.api.CommonLang"
-          + "uageSettings\"\317\002\n\016MethodSettings\022\020\n\010selec"
-          + "tor\030\001 \001(\t\022<\n\014long_running\030\002 \001(\0132&.google"
-          + ".api.MethodSettings.LongRunning\022\035\n\025auto_"
-          + "populated_fields\030\003 \003(\t\032\315\001\n\013LongRunning\0225"
-          + "\n\022initial_poll_delay\030\001 \001(\0132\031.google.prot"
-          + "obuf.Duration\022\035\n\025poll_delay_multiplier\030\002"
-          + " \001(\002\0221\n\016max_poll_delay\030\003 \001(\0132\031.google.pr"
-          + "otobuf.Duration\0225\n\022total_poll_timeout\030\004 "
-          + "\001(\0132\031.google.protobuf.Duration*\243\001\n\031Clien"
-          + "tLibraryOrganization\022+\n\'CLIENT_LIBRARY_O"
-          + "RGANIZATION_UNSPECIFIED\020\000\022\t\n\005CLOUD\020\001\022\007\n\003"
-          + "ADS\020\002\022\n\n\006PHOTOS\020\003\022\017\n\013STREET_VIEW\020\004\022\014\n\010SH"
-          + "OPPING\020\005\022\007\n\003GEO\020\006\022\021\n\rGENERATIVE_AI\020\007*g\n\030"
-          + "ClientLibraryDestination\022*\n&CLIENT_LIBRA"
-          + "RY_DESTINATION_UNSPECIFIED\020\000\022\n\n\006GITHUB\020\n"
-          + "\022\023\n\017PACKAGE_MANAGER\020\024:9\n\020method_signatur"
-          + "e\022\036.google.protobuf.MethodOptions\030\233\010 \003(\t"
-          + ":6\n\014default_host\022\037.google.protobuf.Servi"
-          + "ceOptions\030\231\010 \001(\t:6\n\014oauth_scopes\022\037.googl"
-          + "e.protobuf.ServiceOptions\030\232\010 \001(\tBi\n\016com."
-          + "google.apiB\013ClientProtoP\001ZAgoogle.golang"
-          + ".org/genproto/googleapis/api/annotations"
-          + ";annotations\242\002\004GAPIb\006proto3"
+          + "nce_documentation_uri\030n \001(\t\022(\n rest_refe"
+          + "rence_documentation_uri\030o \001(\t\"\343\001\n\014JavaSe"
+          + "ttings\022\027\n\017library_package\030\001 \001(\t\022L\n\023servi"
+          + "ce_class_names\030\002 \003(\0132/.google.api.JavaSe"
+          + "ttings.ServiceClassNamesEntry\0222\n\006common\030"
+          + "\003 \001(\0132\".google.api.CommonLanguageSetting"
+          + "s\0328\n\026ServiceClassNamesEntry\022\013\n\003key\030\001 \001(\t"
+          + "\022\r\n\005value\030\002 \001(\t:\0028\001\"A\n\013CppSettings\0222\n\006co"
+          + "mmon\030\001 \001(\0132\".google.api.CommonLanguageSe"
+          + "ttings\"A\n\013PhpSettings\0222\n\006common\030\001 \001(\0132\"."
+          + "google.api.CommonLanguageSettings\"D\n\016Pyt"
+          + "honSettings\0222\n\006common\030\001 \001(\0132\".google.api"
+          + ".CommonLanguageSettings\"B\n\014NodeSettings\022"
+          + "2\n\006common\030\001 \001(\0132\".google.api.CommonLangu"
+          + "ageSettings\"\252\003\n\016DotnetSettings\0222\n\006common"
+          + "\030\001 \001(\0132\".google.api.CommonLanguageSettin"
+          + "gs\022I\n\020renamed_services\030\002 \003(\0132/.google.ap"
+          + "i.DotnetSettings.RenamedServicesEntry\022K\n"
+          + "\021renamed_resources\030\003 \003(\01320.google.api.Do"
+          + "tnetSettings.RenamedResourcesEntry\022\031\n\021ig"
+          + "nored_resources\030\004 \003(\t\022 \n\030forced_namespac"
+          + "e_aliases\030\005 \003(\t\022\036\n\026handwritten_signature"
+          + "s\030\006 \003(\t\0326\n\024RenamedServicesEntry\022\013\n\003key\030\001"
+          + " \001(\t\022\r\n\005value\030\002 \001(\t:\0028\001\0327\n\025RenamedResour"
+          + "cesEntry\022\013\n\003key\030\001 \001(\t\022\r\n\005value\030\002 \001(\t:\0028\001"
+          + "\"B\n\014RubySettings\0222\n\006common\030\001 \001(\0132\".googl"
+          + "e.api.CommonLanguageSettings\"@\n\nGoSettin"
+          + "gs\0222\n\006common\030\001 \001(\0132\".google.api.CommonLa"
+          + "nguageSettings\"\317\002\n\016MethodSettings\022\020\n\010sel"
+          + "ector\030\001 \001(\t\022<\n\014long_running\030\002 \001(\0132&.goog"
+          + "le.api.MethodSettings.LongRunning\022\035\n\025aut"
+          + "o_populated_fields\030\003 \003(\t\032\315\001\n\013LongRunning"
+          + "\0225\n\022initial_poll_delay\030\001 \001(\0132\031.google.pr"
+          + "otobuf.Duration\022\035\n\025poll_delay_multiplier"
+          + "\030\002 \001(\002\0221\n\016max_poll_delay\030\003 \001(\0132\031.google."
+          + "protobuf.Duration\0225\n\022total_poll_timeout\030"
+          + "\004 \001(\0132\031.google.protobuf.Duration*\243\001\n\031Cli"
+          + "entLibraryOrganization\022+\n\'CLIENT_LIBRARY"
+          + "_ORGANIZATION_UNSPECIFIED\020\000\022\t\n\005CLOUD\020\001\022\007"
+          + "\n\003ADS\020\002\022\n\n\006PHOTOS\020\003\022\017\n\013STREET_VIEW\020\004\022\014\n\010"
+          + "SHOPPING\020\005\022\007\n\003GEO\020\006\022\021\n\rGENERATIVE_AI\020\007*g"
+          + "\n\030ClientLibraryDestination\022*\n&CLIENT_LIB"
+          + "RARY_DESTINATION_UNSPECIFIED\020\000\022\n\n\006GITHUB"
+          + "\020\n\022\023\n\017PACKAGE_MANAGER\020\024:9\n\020method_signat"
+          + "ure\022\036.google.protobuf.MethodOptions\030\233\010 \003"
+          + "(\t:6\n\014default_host\022\037.google.protobuf.Ser"
+          + "viceOptions\030\231\010 \001(\t:6\n\014oauth_scopes\022\037.goo"
+          + "gle.protobuf.ServiceOptions\030\232\010 \001(\t:8\n\013ap"
+          + "i_version\022\037.google.protobuf.ServiceOptio"
+          + "ns\030\301\272\253\372\001 \001(\tBi\n\016com.google.apiB\013ClientPr"
+          + "otoP\001ZAgoogle.golang.org/genproto/google"
+          + "apis/api/annotations;annotations\242\002\004GAPIb"
+          + "\006proto3"
     };
     descriptor =
         com.google.protobuf.Descriptors.FileDescriptor.internalBuildGeneratedFileFrom(
@@ -342,6 +375,7 @@ public static com.google.protobuf.Descriptors.FileDescriptor getDescriptor() {
               "Organization",
               "LibrarySettings",
               "ProtoReferenceDocumentationUri",
+              "RestReferenceDocumentationUri",
             });
     internal_static_google_api_JavaSettings_descriptor = getDescriptor().getMessageTypes().get(3);
     internal_static_google_api_JavaSettings_fieldAccessorTable =
@@ -447,6 +481,7 @@ public static com.google.protobuf.Descriptors.FileDescriptor getDescriptor() {
     methodSignature.internalInit(descriptor.getExtensions().get(0));
     defaultHost.internalInit(descriptor.getExtensions().get(1));
     oauthScopes.internalInit(descriptor.getExtensions().get(2));
+    apiVersion.internalInit(descriptor.getExtensions().get(3));
     com.google.api.LaunchStageProto.getDescriptor();
     com.google.protobuf.DescriptorProtos.getDescriptor();
     com.google.protobuf.DurationProto.getDescriptor();

java-common-protos/proto-google-common-protos/src/main/java/com/google/api/CommonLanguageSettings.java

@@ -78,7 +78,7 @@ public static final com.google.protobuf.Descriptors.Descriptor getDescriptor() {
    * <code>string reference_docs_uri = 1 [deprecated = true];</code>
    *
    * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-   *     google/api/client.proto;l=106
+   *     google/api/client.proto;l=122
    * @return The referenceDocsUri.
    */
   @java.lang.Override
@@ -105,7 +105,7 @@ public java.lang.String getReferenceDocsUri() {
    * <code>string reference_docs_uri = 1 [deprecated = true];</code>
    *
    * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-   *     google/api/client.proto;l=106
+   *     google/api/client.proto;l=122
    * @return The bytes for referenceDocsUri.
    */
   @java.lang.Override
@@ -637,7 +637,7 @@ public Builder mergeFrom(
      * <code>string reference_docs_uri = 1 [deprecated = true];</code>
      *
      * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-     *     google/api/client.proto;l=106
+     *     google/api/client.proto;l=122
      * @return The referenceDocsUri.
      */
     @java.lang.Deprecated
@@ -663,7 +663,7 @@ public java.lang.String getReferenceDocsUri() {
      * <code>string reference_docs_uri = 1 [deprecated = true];</code>
      *
      * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-     *     google/api/client.proto;l=106
+     *     google/api/client.proto;l=122
      * @return The bytes for referenceDocsUri.
      */
     @java.lang.Deprecated
@@ -689,7 +689,7 @@ public com.google.protobuf.ByteString getReferenceDocsUriBytes() {
      * <code>string reference_docs_uri = 1 [deprecated = true];</code>
      *
      * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-     *     google/api/client.proto;l=106
+     *     google/api/client.proto;l=122
      * @param value The referenceDocsUri to set.
      * @return This builder for chaining.
      */
@@ -714,7 +714,7 @@ public Builder setReferenceDocsUri(java.lang.String value) {
      * <code>string reference_docs_uri = 1 [deprecated = true];</code>
      *
      * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-     *     google/api/client.proto;l=106
+     *     google/api/client.proto;l=122
      * @return This builder for chaining.
      */
     @java.lang.Deprecated
@@ -735,7 +735,7 @@ public Builder clearReferenceDocsUri() {
      * <code>string reference_docs_uri = 1 [deprecated = true];</code>
      *
      * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-     *     google/api/client.proto;l=106
+     *     google/api/client.proto;l=122
      * @param value The bytes for referenceDocsUri to set.
      * @return This builder for chaining.
      */

java-common-protos/proto-google-common-protos/src/main/java/com/google/api/CommonLanguageSettingsOrBuilder.java

@@ -35,7 +35,7 @@ public interface CommonLanguageSettingsOrBuilder
    * <code>string reference_docs_uri = 1 [deprecated = true];</code>
    *
    * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-   *     google/api/client.proto;l=106
+   *     google/api/client.proto;l=122
    * @return The referenceDocsUri.
    */
   @java.lang.Deprecated
@@ -51,7 +51,7 @@ public interface CommonLanguageSettingsOrBuilder
    * <code>string reference_docs_uri = 1 [deprecated = true];</code>
    *
    * @deprecated google.api.CommonLanguageSettings.reference_docs_uri is deprecated. See
-   *     google/api/client.proto;l=106
+   *     google/api/client.proto;l=122
    * @return The bytes for referenceDocsUri.
    */
   @java.lang.Deprecated

java-common-protos/proto-google-common-protos/src/main/java/com/google/api/Documentation.java

@@ -35,7 +35,7 @@
  *     content: (== include google/foo/overview.md ==)
  *   - name: Tutorial
  *     content: (== include google/foo/tutorial.md ==)
- *     subpages;
+ *     subpages:
  *     - name: Java
  *       content: (== include google/foo/tutorial_java.md ==)
  *   rules:
@@ -733,7 +733,7 @@ protected Builder newBuilderForType(com.google.protobuf.GeneratedMessageV3.Build
    *     content: (== include google/foo/overview.md ==)
    *   - name: Tutorial
    *     content: (== include google/foo/tutorial.md ==)
-   *     subpages;
+   *     subpages:
    *     - name: Java
    *       content: (== include google/foo/tutorial_java.md ==)
    *   rules:

java-common-protos/proto-google-common-protos/src/main/java/com/google/api/ErrorReason.java

@@ -783,6 +783,32 @@ public enum ErrorReason implements com.google.protobuf.ProtocolMessageEnum {
    * <code>GCP_SUSPENDED = 30;</code>
    */
   GCP_SUSPENDED(30),
+  /**
+   *
+   *
+   * <pre>
+   * The request violates the location policies when creating resources in
+   * the restricted region.
+   *
+   * Example of an ErrorInfo when creating the Cloud Storage Bucket by
+   * "projects/123" for service storage.googleapis.com:
+   *
+   *     { "reason": "LOCATION_POLICY_VIOLATED",
+   *       "domain": "googleapis.com",
+   *       "metadata": {
+   *         "consumer": "projects/123",
+   *         "service": "storage.googleapis.com",
+   *       }
+   *     }
+   *
+   * This response indicates creating the Cloud Storage Bucket in
+   * "locations/asia-northeast3" violates at least one location policy.
+   * The troubleshooting guidance is provided in the Help links.
+   * </pre>
+   *
+   * <code>LOCATION_POLICY_VIOLATED = 31;</code>
+   */
+  LOCATION_POLICY_VIOLATED(31),
   UNRECOGNIZED(-1),
   ;
 
@@ -1531,6 +1557,32 @@ public enum ErrorReason implements com.google.protobuf.ProtocolMessageEnum {
    * <code>GCP_SUSPENDED = 30;</code>
    */
   public static final int GCP_SUSPENDED_VALUE = 30;
+  /**
+   *
+   *
+   * <pre>
+   * The request violates the location policies when creating resources in
+   * the restricted region.
+   *
+   * Example of an ErrorInfo when creating the Cloud Storage Bucket by
+   * "projects/123" for service storage.googleapis.com:
+   *
+   *     { "reason": "LOCATION_POLICY_VIOLATED",
+   *       "domain": "googleapis.com",
+   *       "metadata": {
+   *         "consumer": "projects/123",
+   *         "service": "storage.googleapis.com",
+   *       }
+   *     }
+   *
+   * This response indicates creating the Cloud Storage Bucket in
+   * "locations/asia-northeast3" violates at least one location policy.
+   * The troubleshooting guidance is provided in the Help links.
+   * </pre>
+   *
+   * <code>LOCATION_POLICY_VIOLATED = 31;</code>
+   */
+  public static final int LOCATION_POLICY_VIOLATED_VALUE = 31;
 
   public final int getNumber() {
     if (this == UNRECOGNIZED) {
@@ -1616,6 +1668,8 @@ public static ErrorReason forNumber(int value) {
         return SERVICE_NOT_VISIBLE;
       case 30:
         return GCP_SUSPENDED;
+      case 31:
+        return LOCATION_POLICY_VIOLATED;
       default:
         return null;
     }