feat: added google.api.Service.publishing and client libraries settings

feat: added google.api.JwtLocation.cookie
feat: new fields in enum google.api.ErrorReason
fix: deprecate google.api.Endpoint.aliases
fix: deprecate google.api.BackendRule.min_deadline
docs: minor updates to comments

PiperOrigin-RevId: 488484261

google/api/BUILD.bazel

@@ -40,7 +40,9 @@ proto_library(
     name = "client_proto",
     srcs = ["client.proto"],
     deps = [
+        ":launch_stage_proto",
         "@com_google_protobuf//:descriptor_proto",
+        "@com_google_protobuf//:duration_proto",
     ],
 )
 
@@ -197,6 +199,7 @@ proto_library(
         ":auth_proto",
         ":backend_proto",
         ":billing_proto",
+        ":client_proto",
         ":context_proto",
         ":control_proto",
         ":documentation_proto",
@@ -352,12 +355,14 @@ go_proto_library(
         ":resource_proto",
         ":routing_proto",
     ],
+    deps = [":api_go_proto"],
 )
 
 go_proto_library(
     name = "client_go_proto",
     importpath = "google.golang.org/genproto/googleapis/api/annotations;annotations",
     protos = [":client_proto"],
+    deps = [":api_go_proto"],
 )
 
 go_proto_library(
@@ -396,9 +401,6 @@ go_proto_library(
     protos = [
         ":launch_stage_proto",
     ],
-    deps = [
-        ":annotations_go_proto",
-    ],
 )
 
 go_proto_library(

google/api/auth.proto

@@ -84,6 +84,9 @@ message JwtLocation {
 
     // Specifies URL query parameter name to extract JWT token.
     string query = 2;
+
+    // Specifies cookie name to extract JWT token.
+    string cookie = 4;
   }
 
   // The value prefix. The value format is "value_prefix{token}"
@@ -152,11 +155,12 @@ message AuthProvider {
   // Implement authorizationUrl of securityDefinitions in OpenAPI spec.
   string authorization_url = 5;
 
-  // Defines the locations to extract the JWT.
+  // Defines the locations to extract the JWT.  For now it is only used by the
+  // Cloud Endpoints to store the OpenAPI extension [x-google-jwt-locations]
+  // (https://cloud.google.com/endpoints/docs/openapi/openapi-extensions#x-google-jwt-locations)
   //
-  // JWT locations can be either from HTTP headers or URL query parameters.
+  // JWT locations can be one of HTTP headers, URL query parameters or
-  // The rule is that the first match wins. The checking order is: checking
+  // cookies. The rule is that the first match wins.
-  // all headers first, then URL query parameters.
   //
   // If not specified,  default to use following 3 locations:
   //    1) Authorization: Bearer

google/api/backend.proto

@@ -120,9 +120,8 @@ message BackendRule {
   // varies based on the request protocol and deployment environment.
   double deadline = 3;
 
-  // Minimum deadline in seconds needed for this method. Calls having deadline
+  // Deprecated, do not use.
-  // value lower than this will be rejected.
+  double min_deadline = 4 [deprecated = true];
-  double min_deadline = 4;
 
   // The number of seconds to wait for the completion of a long running
   // operation. The default is no deadline.

google/api/client.proto

@@ -16,7 +16,9 @@ syntax = "proto3";
 
 package google.api;
 
+import "google/api/launch_stage.proto";
 import "google/protobuf/descriptor.proto";
+import "google/protobuf/duration.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";
 option java_multiple_files = true;
@@ -97,3 +99,251 @@ extend google.protobuf.ServiceOptions {
   //   }
   string oauth_scopes = 1050;
 }
+
+// Required information for every language.
+message CommonLanguageSettings {
+  // Link to automatically generated reference documentation.  Example:
+  // https://cloud.google.com/nodejs/docs/reference/asset/latest
+  string reference_docs_uri = 1;
+
+  // The destination where API teams want this client library to be published.
+  repeated ClientLibraryDestination destinations = 2;
+}
+
+// Details about how and where to publish client libraries.
+message ClientLibrarySettings {
+  // Version of the API to apply these settings to.
+  string version = 1;
+
+  // Launch stage of this version of the API.
+  LaunchStage launch_stage = 2;
+
+  // When using transport=rest, the client request will encode enums as
+  // numbers rather than strings.
+  bool rest_numeric_enums = 3;
+
+  // Settings for legacy Java features, supported in the Service YAML.
+  JavaSettings java_settings = 21;
+
+  // Settings for C++ client libraries.
+  CppSettings cpp_settings = 22;
+
+  // Settings for PHP client libraries.
+  PhpSettings php_settings = 23;
+
+  // Settings for Python client libraries.
+  PythonSettings python_settings = 24;
+
+  // Settings for Node client libraries.
+  NodeSettings node_settings = 25;
+
+  // Settings for .NET client libraries.
+  DotnetSettings dotnet_settings = 26;
+
+  // Settings for Ruby client libraries.
+  RubySettings ruby_settings = 27;
+
+  // Settings for Go client libraries.
+  GoSettings go_settings = 28;
+}
+
+// This message configures the settings for publishing [Google Cloud Client
+// libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)
+// generated from the service config.
+message Publishing {
+  // A list of API method settings, e.g. the behavior for methods that use the
+  // long-running operation pattern.
+  repeated MethodSettings method_settings = 2;
+
+  // Link to a place that API users can report issues.  Example:
+  // https://issuetracker.google.com/issues/new?component=190865&template=1161103
+  string new_issue_uri = 101;
+
+  // Link to product home page.  Example:
+  // https://cloud.google.com/asset-inventory/docs/overview
+  string documentation_uri = 102;
+
+  // Used as a tracking tag when collecting data about the APIs developer
+  // relations artifacts like docs, packages delivered to package managers,
+  // etc.  Example: "speech".
+  string api_short_name = 103;
+
+  // GitHub label to apply to issues and pull requests opened for this API.
+  string github_label = 104;
+
+  // GitHub teams to be added to CODEOWNERS in the directory in GitHub
+  // containing source code for the client libraries for this API.
+  repeated string codeowner_github_teams = 105;
+
+  // A prefix used in sample code when demarking regions to be included in
+  // documentation.
+  string doc_tag_prefix = 106;
+
+  // For whom the client library is being published.
+  ClientLibraryOrganization organization = 107;
+
+  // Client library settings.  If the same version string appears multiple
+  // times in this list, then the last one wins.  Settings from earlier
+  // settings with the same version string are discarded.
+  repeated ClientLibrarySettings library_settings = 109;
+}
+
+// Settings for Java client libraries.
+message JavaSettings {
+  // The package name to use in Java. Clobbers the java_package option
+  // set in the protobuf. This should be used **only** by APIs
+  // who have already set the language_settings.java.package_name" field
+  // in gapic.yaml. API teams should use the protobuf java_package option
+  // where possible.
+  //
+  // Example of a YAML configuration::
+  //
+  //  publishing:
+  //    java_settings:
+  //      library_package: com.google.cloud.pubsub.v1
+  string library_package = 1;
+
+  // Configure the Java class name to use instead of the service's for its
+  // corresponding generated GAPIC client. Keys are fully-qualified
+  // service names as they appear in the protobuf (including the full
+  // the language_settings.java.interface_names" field in gapic.yaml. API
+  // teams should otherwise use the service name as it appears in the
+  // protobuf.
+  //
+  // Example of a YAML configuration::
+  //
+  //  publishing:
+  //    java_settings:
+  //      service_class_names:
+  //        - google.pubsub.v1.Publisher: TopicAdmin
+  //        - google.pubsub.v1.Subscriber: SubscriptionAdmin
+  map<string, string> service_class_names = 2;
+
+  // Some settings.
+  CommonLanguageSettings common = 3;
+}
+
+// Settings for C++ client libraries.
+message CppSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Php client libraries.
+message PhpSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Python client libraries.
+message PythonSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Node client libraries.
+message NodeSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Dotnet client libraries.
+message DotnetSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Ruby client libraries.
+message RubySettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Go client libraries.
+message GoSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Describes the generator configuration for a method.
+message MethodSettings {
+  // Describes settings to use when generating API methods that use the
+  // long-running operation pattern.
+  // All default values below are from those used in the client library
+  // generators (e.g.
+  // [Java](https://github.com/googleapis/gapic-generator-java/blob/04c2faa191a9b5a10b92392fe8482279c4404803/src/main/java/com/google/api/generator/gapic/composer/common/RetrySettingsComposer.java)).
+  message LongRunning {
+    // Initial delay after which the first poll request will be made.
+    // Default value: 5 seconds.
+    google.protobuf.Duration initial_poll_delay = 1;
+
+    // Multiplier to gradually increase delay between subsequent polls until it
+    // reaches max_poll_delay.
+    // Default value: 1.5.
+    float poll_delay_multiplier = 2;
+
+    // Maximum time between two subsequent poll requests.
+    // Default value: 45 seconds.
+    google.protobuf.Duration max_poll_delay = 3;
+
+    // Total polling timeout.
+    // Default value: 5 minutes.
+    google.protobuf.Duration total_poll_timeout = 4;
+  }
+
+  // The fully qualified name of the method, for which the options below apply.
+  // This is used to find the method to apply the options.
+  string selector = 1;
+
+  // Describes settings to use for long-running operations when generating
+  // API methods for RPCs. Complements RPCs that use the annotations in
+  // google/longrunning/operations.proto.
+  //
+  // Example of a YAML configuration::
+  //
+  //  publishing:
+  //    method_behavior:
+  //      - selector: CreateAdDomain
+  //        long_running:
+  //          initial_poll_delay:
+  //            seconds: 60 # 1 minute
+  //          poll_delay_multiplier: 1.5
+  //          max_poll_delay:
+  //            seconds: 360 # 6 minutes
+  //          total_poll_timeout:
+  //             seconds: 54000 # 90 minutes
+  LongRunning long_running = 2;
+}
+
+// The organization for which the client libraries are being published.
+// Affects the url where generated docs are published, etc.
+enum ClientLibraryOrganization {
+  // Not useful.
+  CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0;
+
+  // Google Cloud Platform Org.
+  CLOUD = 1;
+
+  // Ads (Advertising) Org.
+  ADS = 2;
+
+  // Photos Org.
+  PHOTOS = 3;
+
+  // Street View Org.
+  STREET_VIEW = 4;
+}
+
+// To where should client libraries be published?
+enum ClientLibraryDestination {
+  // Client libraries will neither be generated nor published to package
+  // managers.
+  CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0;
+
+  // Generate the client library in a repo under github.com/googleapis,
+  // but don't publish it to package managers.
+  GITHUB = 10;
+
+  // Publish the library to package managers like nuget.org and npmjs.com.
+  PACKAGE_MANAGER = 20;
+}

google/api/control.proto

@@ -22,11 +22,15 @@ option java_outer_classname = "ControlProto";
 option java_package = "com.google.api";
 option objc_class_prefix = "GAPI";
 
-// Selects and configures the service controller used by the service.  The
+// Selects and configures the service controller used by the service.
-// service controller handles features like abuse, quota, billing, logging,
+//
-// monitoring, etc.
+// Example:
+//
+//     control:
+//       environment: servicecontrol.googleapis.com
 message Control {
-  // The service control environment to use. If empty, no control plane
+  // The service controller environment to use. If empty, no control plane
-  // feature (like quota and billing) will be enabled.
+  // feature (like quota and billing) will be enabled. The recommended value for
+  // most services is servicecontrol.googleapis.com
   string environment = 1;
 }

google/api/documentation.proto

@@ -78,8 +78,10 @@ option objc_class_prefix = "GAPI";
 // The directive `suppress_warning` does not directly affect documentation
 // and is documented together with service config validation.
 message Documentation {
-  // A short summary of what the service does. Can only be provided by
+  // A short description of what the service does. The summary must be plain
-  // plain text.
+  // text. It becomes the overview of the service displayed in Google Cloud
+  // Console.
+  // NOTE: This field is equivalent to the standard field `description`.
   string summary = 1;
 
   // The top level pages for the documentation set.
@@ -117,15 +119,18 @@ message Documentation {
 
 // A documentation rule provides information about individual API elements.
 message DocumentationRule {
-  // The selector is a comma-separated list of patterns. Each pattern is a
+  // The selector is a comma-separated list of patterns for any element such as
-  // qualified name of the element which may end in "*", indicating a wildcard.
+  // a method, a field, an enum value. Each pattern is a qualified name of the
-  // Wildcards are only allowed at the end and for a whole component of the
+  // element which may end in "*", indicating a wildcard. Wildcards are only
-  // qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A
+  // allowed at the end and for a whole component of the qualified name,
-  // wildcard will match one or more components. To specify a default for all
+  // i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A wildcard will match
-  // applicable elements, the whole pattern "*" is used.
+  // one or more components. To specify a default for all applicable elements,
+  // the whole pattern "*" is used.
   string selector = 1;
 
-  // Description of the selected API(s).
+  // Description of the selected proto element (e.g. a message, a method, a
+  // 'service' definition, or a field). Defaults to leading & trailing comments
+  // taken from the proto source definition of the proto element.
   string description = 2;
 
   // Deprecation description of the selected element(s). It can be provided if
@@ -153,7 +158,8 @@ message Page {
   string name = 1;
 
   // The Markdown content of the page. You can use <code>&#40;== include {path}
-  // ==&#41;</code> to include content from a Markdown file.
+  // ==&#41;</code> to include content from a Markdown file. The content can be
+  // used to produce the documentation page such as HTML format page.
   string content = 2;
 
   // Subpages of this page. The order of subpages specified here will be

google/api/endpoint.proto

@@ -22,21 +22,26 @@ option java_outer_classname = "EndpointProto";
 option java_package = "com.google.api";
 option objc_class_prefix = "GAPI";
 
-// `Endpoint` describes a network endpoint of a service that serves a set of
+// `Endpoint` describes a network address of a service that serves a set of
 // APIs. It is commonly known as a service endpoint. A service may expose
 // any number of service endpoints, and all service endpoints share the same
 // service definition, such as quota limits and monitoring metrics.
 //
-// Example service configuration:
+// Example:
 //
+//     type: google.api.Service
 //     name: library-example.googleapis.com
 //     endpoints:
-//       # Below entry makes 'google.example.library.v1.Library'
+//       # Declares network address `https://library-example.googleapis.com`
-//       # API be served from endpoint address library-example.googleapis.com.
+//       # for service `library-example.googleapis.com`. The `https` scheme
-//       # It also allows HTTP OPTIONS calls to be passed to the backend, for
+//       # is implicit for all service endpoints. Other schemes may be
-//       # it to decide whether the subsequent cross-origin request is
+//       # supported in the future.
-//       # allowed to proceed.
 //     - name: library-example.googleapis.com
+//       allow_cors: false
+//     - name: content-staging-library-example.googleapis.com
+//       # Allows HTTP OPTIONS calls to be passed to the API frontend, for it
+//       # to decide whether the subsequent cross-origin request is allowed
+//       # to proceed.
 //       allow_cors: true
 message Endpoint {
   // The canonical name of this endpoint.
@@ -45,8 +50,8 @@ message Endpoint {
   // Unimplemented. Dot not use.
   //
   // DEPRECATED: This field is no longer supported. Instead of using aliases,
-  // please specify multiple [google.api.Endpoint][google.api.Endpoint] for each of the intended
+  // please specify multiple [google.api.Endpoint][google.api.Endpoint] for each
-  // aliases.
+  // of the intended aliases.
   //
   // Additional names that this endpoint will be hosted on.
   repeated string aliases = 2 [deprecated = true];

google/api/error_reason.proto

@@ -394,4 +394,142 @@ enum ErrorReason {
   //       }
   //     }
   ACCESS_TOKEN_TYPE_UNSUPPORTED = 19;
+
+  // The request is denied because the request doesn't have any authentication
+  // credentials. For more information regarding the supported authentication
+  // strategies for Google Cloud APIs, see
+  // https://cloud.google.com/docs/authentication.
+  //
+  // Example of an ErrorInfo when the request is to the Cloud Storage API
+  // without any authentication credentials.
+  //
+  //     { "reason": "CREDENTIALS_MISSING",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "service": "storage.googleapis.com",
+  //         "method": "google.storage.v1.Storage.GetObject"
+  //       }
+  //     }
+  CREDENTIALS_MISSING = 20;
+
+  // The request is denied because the provided project owning the resource
+  // which acts as the [API
+  // consumer](https://cloud.google.com/apis/design/glossary#api_consumer) is
+  // invalid. It may be in a bad format or empty.
+  //
+  // Example of an ErrorInfo when the request is to the Cloud Functions API,
+  // but the offered resource project in the request in a bad format which can't
+  // perform the ListFunctions method.
+  //
+  //     { "reason": "RESOURCE_PROJECT_INVALID",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "service": "cloudfunctions.googleapis.com",
+  //         "method":
+  //         "google.cloud.functions.v1.CloudFunctionsService.ListFunctions"
+  //       }
+  //     }
+  RESOURCE_PROJECT_INVALID = 21;
+
+  // The request is denied because the provided session cookie is missing,
+  // invalid or failed to decode.
+  //
+  // Example of an ErrorInfo when the request is calling Cloud Storage service
+  // with a SID cookie which can't be decoded.
+  //
+  //     { "reason": "SESSION_COOKIE_INVALID",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "service": "storage.googleapis.com",
+  //         "method": "google.storage.v1.Storage.GetObject",
+  //         "cookie": "SID"
+  //       }
+  //     }
+  SESSION_COOKIE_INVALID = 23;
+
+  // The request is denied because the user is from a Google Workspace customer
+  // that blocks their users from accessing a particular service.
+  //
+  // Example scenario: https://support.google.com/a/answer/9197205?hl=en
+  //
+  // Example of an ErrorInfo when access to Google Cloud Storage service is
+  // blocked by the Google Workspace administrator:
+  //
+  //     { "reason": "USER_BLOCKED_BY_ADMIN",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "service": "storage.googleapis.com",
+  //         "method": "google.storage.v1.Storage.GetObject",
+  //       }
+  //     }
+  USER_BLOCKED_BY_ADMIN = 24;
+
+  // The request is denied because the resource service usage is restricted
+  // by administrators according to the organization policy constraint.
+  // For more information see
+  // https://cloud.google.com/resource-manager/docs/organization-policy/restricting-services.
+  //
+  // Example of an ErrorInfo when access to Google Cloud Storage service is
+  // restricted by Resource Usage Restriction policy:
+  //
+  //     { "reason": "RESOURCE_USAGE_RESTRICTION_VIOLATED",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "consumer": "projects/project-123",
+  //         "service": "storage.googleapis.com"
+  //       }
+  //     }
+  RESOURCE_USAGE_RESTRICTION_VIOLATED = 25;
+
+  // Unimplemented. Do not use.
+  //
+  // The request is denied because it contains unsupported system parameters in
+  // URL query parameters or HTTP headers. For more information,
+  // see https://cloud.google.com/apis/docs/system-parameters
+  //
+  // Example of an ErrorInfo when access "pubsub.googleapis.com" service with
+  // a request header of "x-goog-user-ip":
+  //
+  //     { "reason": "SYSTEM_PARAMETER_UNSUPPORTED",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "service": "pubsub.googleapis.com"
+  //         "parameter": "x-goog-user-ip"
+  //       }
+  //     }
+  SYSTEM_PARAMETER_UNSUPPORTED = 26;
+
+  // The request is denied because it violates Org Restriction: the requested
+  // resource does not belong to allowed organizations specified in
+  // "X-Goog-Allowed-Resources" header.
+  //
+  // Example of an ErrorInfo when accessing a GCP resource that is restricted by
+  // Org Restriction for "pubsub.googleapis.com" service.
+  //
+  // {
+  //   reason: "ORG_RESTRICTION_VIOLATION"
+  //   domain: "googleapis.com"
+  //   metadata {
+  //     "consumer":"projects/123456"
+  //     "service": "pubsub.googleapis.com"
+  //   }
+  // }
+  ORG_RESTRICTION_VIOLATION = 27;
+
+  // The request is denied because "X-Goog-Allowed-Resources" header is in a bad
+  // format.
+  //
+  // Example of an ErrorInfo when
+  // accessing "pubsub.googleapis.com" service with an invalid
+  // "X-Goog-Allowed-Resources" request header.
+  //
+  // {
+  //   reason: "ORG_RESTRICTION_HEADER_INVALID"
+  //   domain: "googleapis.com"
+  //   metadata {
+  //     "consumer":"projects/123456"
+  //     "service": "pubsub.googleapis.com"
+  //   }
+  // }
+  ORG_RESTRICTION_HEADER_INVALID = 28;
 }

google/api/launch_stage.proto

@@ -23,7 +23,7 @@ option java_package = "com.google.api";
 option objc_class_prefix = "GAPI";
 
 // The launch stage as defined by [Google Cloud Platform
-// Launch Stages](http://cloud.google.com/terms/launch-stages).
+// Launch Stages](https://cloud.google.com/terms/launch-stages).
 enum LaunchStage {
   // Do not use this default value.
   LAUNCH_STAGE_UNSPECIFIED = 0;
@@ -45,7 +45,7 @@ enum LaunchStage {
   // for widespread use. By Alpha, all significant design issues are resolved
   // and we are in the process of verifying functionality. Alpha customers
   // need to apply for access, agree to applicable terms, and have their
-  // projects allowlisted. Alpha releases don’t have to be feature complete,
+  // projects allowlisted. Alpha releases don't have to be feature complete,
   // no SLAs are provided, and there are no technical support obligations, but
   // they will be far enough along that customers can actually use them in
   // test environments or for limited-use tests -- just like they would in
@@ -64,7 +64,7 @@ enum LaunchStage {
   GA = 4;
 
   // Deprecated features are scheduled to be shut down and removed. For more
-  // information, see the “Deprecation Policy” section of our [Terms of
+  // information, see the "Deprecation Policy" section of our [Terms of
   // Service](https://cloud.google.com/terms/)
   // and the [Google Cloud Platform Subject to the Deprecation
   // Policy](https://cloud.google.com/terms/deprecation) documentation.

google/api/metric.proto

@@ -31,23 +31,6 @@ option objc_class_prefix = "GAPI";
 // existing data unusable.
 //
 message MetricDescriptor {
-  // Additional annotations that can be used to guide the usage of a metric.
-  message MetricDescriptorMetadata {
-    // Deprecated. Must use the [MetricDescriptor.launch_stage][google.api.MetricDescriptor.launch_stage] instead.
-    LaunchStage launch_stage = 1 [deprecated = true];
-
-    // The sampling period of metric data points. For metrics which are written
-    // periodically, consecutive data points are stored at this time interval,
-    // excluding data loss due to errors. Metrics with a higher granularity have
-    // a smaller sampling period.
-    google.protobuf.Duration sample_period = 2;
-
-    // The delay of data points caused by ingestion. Data points older than this
-    // age are guaranteed to be ingested and available to be read, excluding
-    // data loss due to errors.
-    google.protobuf.Duration ingest_delay = 3;
-  }
-
   // The kind of measurement. It describes how the data is reported.
   // For information on setting the start time and end time based on
   // the MetricKind, see [TimeInterval][google.monitoring.v3.TimeInterval].
@@ -95,6 +78,23 @@ message MetricDescriptor {
     MONEY = 6;
   }
 
+  // Additional annotations that can be used to guide the usage of a metric.
+  message MetricDescriptorMetadata {
+    // Deprecated. Must use the [MetricDescriptor.launch_stage][google.api.MetricDescriptor.launch_stage] instead.
+    LaunchStage launch_stage = 1 [deprecated = true];
+
+    // The sampling period of metric data points. For metrics which are written
+    // periodically, consecutive data points are stored at this time interval,
+    // excluding data loss due to errors. Metrics with a higher granularity have
+    // a smaller sampling period.
+    google.protobuf.Duration sample_period = 2;
+
+    // The delay of data points caused by ingestion. Data points older than this
+    // age are guaranteed to be ingested and available to be read, excluding
+    // data loss due to errors.
+    google.protobuf.Duration ingest_delay = 3;
+  }
+
   // The resource name of the metric descriptor.
   string name = 1;
 

google/api/monitored_resource.proto

@@ -48,6 +48,10 @@ message MonitoredResourceDescriptor {
 
   // Required. The monitored resource type. For example, the type
   // `"cloudsql_database"` represents databases in Google Cloud SQL.
+  //  For a list of types, see [Monitoring resource
+  //  types](https://cloud.google.com/monitoring/api/resources)
+  // and [Logging resource
+  // types](https://cloud.google.com/logging/docs/api/v2/resource-list).
   string type = 1;
 
   // Optional. A concise name for the monitored resource type that might be
@@ -77,15 +81,18 @@ message MonitoredResourceDescriptor {
 // its attributes according to the schema. For example, a particular Compute
 // Engine VM instance could be represented by the following object, because the
 // [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] for `"gce_instance"` has labels
-// `"instance_id"` and `"zone"`:
+// `"project_id"`, `"instance_id"` and `"zone"`:
 //
 //     { "type": "gce_instance",
-//       "labels": { "instance_id": "12345678901234",
+//       "labels": { "project_id": "my-project",
+//                   "instance_id": "12345678901234",
 //                   "zone": "us-central1-a" }}
 message MonitoredResource {
   // Required. The monitored resource type. This field must match
   // the `type` field of a [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] object. For
   // example, the type of a Compute Engine VM instance is `gce_instance`.
+  // Some descriptors include the service name in the type; for example,
+  // the type of a Datastream stream is `datastream.googleapis.com/Stream`.
   string type = 1;
 
   // Required. Values for all of the labels listed in the associated monitored

google/api/quota.proto

@@ -44,10 +44,10 @@ option objc_class_prefix = "GAPI";
 //          STANDARD: 10000
 //
 //
-//      # The metric rules bind all methods to the read_calls metric,
+//      (The metric rules bind all methods to the read_calls metric,
-//      # except for the UpdateBook and DeleteBook methods. These two methods
+//       except for the UpdateBook and DeleteBook methods. These two methods
-//      # are mapped to the write_calls metric, with the UpdateBook method
+//       are mapped to the write_calls metric, with the UpdateBook method
-//      # consuming at twice rate as the DeleteBook method.
+//       consuming at twice rate as the DeleteBook method.)
 //      metric_rules:
 //      - selector: "*"
 //        metric_costs:
@@ -74,10 +74,10 @@ option objc_class_prefix = "GAPI";
 //
 //
 message Quota {
-  // List of `QuotaLimit` definitions for the service.
+  // List of QuotaLimit definitions for the service.
   repeated QuotaLimit limits = 3;
 
-  // List of `MetricRule` definitions, each one mapping a selected method to one
+  // List of MetricRule definitions, each one mapping a selected method to one
   // or more metrics.
   repeated MetricRule metric_rules = 4;
 }

google/api/service.proto

@@ -19,6 +19,7 @@ package google.api;
 import "google/api/auth.proto";
 import "google/api/backend.proto";
 import "google/api/billing.proto";
+import "google/api/client.proto";
 import "google/api/context.proto";
 import "google/api/control.proto";
 import "google/api/documentation.proto";
@@ -43,11 +44,12 @@ option java_outer_classname = "ServiceProto";
 option java_package = "com.google.api";
 option objc_class_prefix = "GAPI";
 
-// `Service` is the root object of Google service configuration schema. It
+// `Service` is the root object of Google API service configuration (service
-// describes basic information about a service, such as the name and the
+// config). It describes the basic information about a logical service,
-// title, and delegates other aspects to sub-sections. Each sub-section is
+// such as the service name and the user-facing title, and delegates other
-// either a proto message or a repeated proto message that configures a
+// aspects to sub-sections. Each sub-section is either a proto message or a
-// specific aspect, such as auth. See each proto message definition for details.
+// repeated proto message that configures a specific aspect, such as auth.
+// For more information, see each proto message definition.
 //
 // Example:
 //
@@ -56,6 +58,16 @@ option objc_class_prefix = "GAPI";
 //     title: Google Calendar API
 //     apis:
 //     - name: google.calendar.v3.Calendar
+//
+//     visibility:
+//       rules:
+//       - selector: "google.calendar.v3.*"
+//         restriction: PREVIEW
+//     backend:
+//       rules:
+//       - selector: "google.calendar.v3.*"
+//         address: calendar.example.com
+//
 //     authentication:
 //       providers:
 //       - id: google_calendar_auth
@@ -72,7 +84,8 @@ message Service {
   // of the service also owns the DNS name.
   string name = 1;
 
-  // The product title for this service.
+  // The product title for this service, it is the name displayed in Google
+  // Cloud Console.
   string title = 2;
 
   // The Google project that owns this service.
@@ -92,19 +105,19 @@ message Service {
   repeated google.protobuf.Api apis = 3;
 
   // A list of all proto message types included in this API service.
-  // Types referenced directly or indirectly by the `apis` are
+  // Types referenced directly or indirectly by the `apis` are automatically
-  // automatically included.  Messages which are not referenced but
+  // included.  Messages which are not referenced but shall be included, such as
-  // shall be included, such as types used by the `google.protobuf.Any` type,
+  // types used by the `google.protobuf.Any` type, should be listed here by
-  // should be listed here by name. Example:
+  // name by the configuration author. Example:
   //
   //     types:
   //     - name: google.protobuf.Int32
   repeated google.protobuf.Type types = 4;
 
-  // A list of all enum types included in this API service.  Enums
+  // A list of all enum types included in this API service.  Enums referenced
-  // referenced directly or indirectly by the `apis` are automatically
+  // directly or indirectly by the `apis` are automatically included.  Enums
-  // included.  Enums which are not referenced but shall be included
+  // which are not referenced but shall be included should be listed here by
-  // should be listed here by name. Example:
+  // name by the configuration author. Example:
   //
   //     enums:
   //     - name: google.someapi.v1.SomeEnum
@@ -164,9 +177,14 @@ message Service {
   // Output only. The source information for this configuration if available.
   SourceInfo source_info = 37;
 
+  // Settings for [Google Cloud Client
+  // libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)
+  // generated from APIs defined as protocol buffers.
+  Publishing publishing = 45;
+
   // Obsolete. Do not use.
   //
   // This field has no semantic meaning. The service config compiler always
   // sets this field to `3`.
-  google.protobuf.UInt32Value config_version = 20 [deprecated = true];
+  google.protobuf.UInt32Value config_version = 20;
 }

google/api/serviceconfig.yaml

@@ -15,6 +15,7 @@ types:
 - name: google.api.MonitoredResourceMetadata
 - name: google.api.ResourceDescriptor
 - name: google.api.ResourceReference
+- name: google.api.RoutingRule
 - name: google.api.Service
 - name: google.api.Visibility
 

google/api/visibility.proto

@@ -55,16 +55,17 @@ extend google.protobuf.ServiceOptions {
   google.api.VisibilityRule api_visibility = 72295727;
 }
 
-// `Visibility` defines restrictions for the visibility of service
+// `Visibility` restricts service consumer's access to service elements,
-// elements.  Restrictions are specified using visibility labels
+// such as whether an application can call a visibility-restricted method.
-// (e.g., PREVIEW) that are elsewhere linked to users and projects.
+// The restriction is expressed by applying visibility labels on service
+// elements. The visibility labels are elsewhere linked to service consumers.
 //
-// Users and projects can have access to more than one visibility label. The
+// A service can define multiple visibility labels, but a service consumer
-// effective visibility for multiple labels is the union of each label's
+// should be granted at most one visibility label. Multiple visibility
-// elements, plus any unrestricted elements.
+// labels for a single service consumer are not supported.
 //
-// If an element and its parents have no restrictions, visibility is
+// If an element and all its parents have no visibility label, its visibility
-// unconditionally granted.
+// is unconditionally granted.
 //
 // Example:
 //
@@ -89,7 +90,8 @@ message Visibility {
 message VisibilityRule {
   // Selects methods, messages, fields, enums, etc. to which this rule applies.
   //
-  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax
+  // details.
   string selector = 1;
 
   // A comma-separated list of visibility labels that apply to the `selector`.