open-telemetry · lalitb · Sep 10, 2024 · Sep 10, 2024
@@ -1,4 +1,4 @@
-// Copyright 2015 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -98,6 +98,22 @@ extend google.protobuf.ServiceOptions {
   //     ...
   //   }
   string oauth_scopes = 1050;
+
+  // 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";
+  //   }
+  string api_version = 525000001;
 }
 
 // Required information for every language.
@@ -192,6 +208,10 @@ message Publishing {
   // Optional link to proto reference documentation.  Example:
   // https://cloud.google.com/pubsub/lite/docs/reference/rpc
   string proto_reference_documentation_uri = 110;
+
+  // Optional link to REST reference documentation.  Example:
+  // https://cloud.google.com/pubsub/lite/docs/reference/rest
+  string rest_reference_documentation_uri = 111;
 }
 
 // Settings for Java client libraries.
@@ -243,8 +263,22 @@ message PhpSettings {
 
 // Settings for Python client libraries.
 message PythonSettings {
+  // Experimental features to be included during client library generation.
+  // These fields will be deprecated once the feature graduates and is enabled
+  // by default.
+  message ExperimentalFeatures {
+    // Enables generation of asynchronous REST clients if `rest` transport is
+    // enabled. By default, asynchronous REST clients will not be generated.
+    // This feature will be enabled by default 1 month after launching the
+    // feature in preview packages.
+    bool rest_async_io_enabled = 1;
+  }
+
   // Some settings.
   CommonLanguageSettings common = 1;
+
+  // Experimental features to be included during client library generation.
+  ExperimentalFeatures experimental_features = 2;
 }
 
 // Settings for Node client libraries.
@@ -329,6 +363,13 @@ message MethodSettings {
 
   // The fully qualified name of the method, for which the options below apply.
   // This is used to find the method to apply the options.
+  //
+  // Example:
+  //
+  //    publishing:
+  //      method_settings:
+  //      - selector: google.storage.control.v2.StorageControl.CreateFolder
+  //        # method settings for CreateFolder...
   string selector = 1;
 
   // Describes settings to use for long-running operations when generating
@@ -337,17 +378,14 @@ message MethodSettings {
   //
   // Example of a YAML configuration::
   //
-  //  publishing:
-  //    method_settings:
+  //    publishing:
+  //      method_settings:
   //      - selector: google.cloud.speech.v2.Speech.BatchRecognize
   //        long_running:
-  //          initial_poll_delay:
-  //            seconds: 60 # 1 minute
+  //          initial_poll_delay: 60s # 1 minute
   //          poll_delay_multiplier: 1.5
-  //          max_poll_delay:
-  //            seconds: 360 # 6 minutes
-  //          total_poll_timeout:
-  //             seconds: 54000 # 90 minutes
+  //          max_poll_delay: 360s # 6 minutes
+  //          total_poll_timeout: 54000s # 90 minutes
   LongRunning long_running = 2;
 
   // List of top-level fields of the request message, that should be
@@ -356,8 +394,8 @@ message MethodSettings {
   //
   // Example of a YAML configuration:
   //
-  //  publishing:
-  //    method_settings:
+  //    publishing:
+  //      method_settings:
   //      - selector: google.example.v1.ExampleService.CreateExample
   //        auto_populated_fields:
   //        - request_id

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -41,7 +41,7 @@ message Http {
   bool fully_decode_reserved_expansion = 2;
 }
 
-// # gRPC Transcoding
+// gRPC Transcoding
 //
 // gRPC Transcoding is a feature for mapping between a gRPC method and one or
 // more HTTP REST endpoints. It allows developers to build a single API service
@@ -82,9 +82,8 @@ message Http {
 //
 // This enables an HTTP REST to gRPC mapping as below:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456`  | `GetMessage(name: "messages/123456")`
+// - HTTP: `GET /v1/messages/123456`
+// - gRPC: `GetMessage(name: "messages/123456")`
 //
 // Any fields in the request message which are not bound by the path template
 // automatically become HTTP query parameters if there is no HTTP request body.
@@ -108,11 +107,9 @@ message Http {
 //
 // This enables a HTTP JSON to RPC mapping as below:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456?revision=2&sub.subfield=foo` |
-// `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:
-// "foo"))`
+// - HTTP: `GET /v1/messages/123456?revision=2&sub.subfield=foo`
+// - gRPC: `GetMessage(message_id: "123456" revision: 2 sub:
+// SubMessage(subfield: "foo"))`
 //
 // Note that fields which are mapped to URL query parameters must have a
 // primitive type or a repeated primitive type or a non-repeated message type.
@@ -142,10 +139,8 @@ message Http {
 // representation of the JSON in the request body is determined by
 // protos JSON encoding:
 //
-// HTTP | gRPC
-// -----|-----
-// `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:
-// "123456" message { text: "Hi!" })`
+// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
+// - gRPC: `UpdateMessage(message_id: "123456" message { text: "Hi!" })`
 //
 // The special name `*` can be used in the body mapping to define that
 // every field not bound by the path template should be mapped to the
@@ -168,10 +163,8 @@ message Http {
 //
 // The following HTTP JSON to RPC mapping is enabled:
 //
-// HTTP | gRPC
-// -----|-----
-// `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:
-// "123456" text: "Hi!")`
+// - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }`
+// - gRPC: `UpdateMessage(message_id: "123456" text: "Hi!")`
 //
 // Note that when using `*` in the body mapping, it is not possible to
 // have HTTP parameters, as all fields not bound by the path end in
@@ -199,13 +192,13 @@ message Http {
 //
 // This enables the following two alternative HTTP JSON to RPC mappings:
 //
-// HTTP | gRPC
-// -----|-----
-// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
-// `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:
-// "123456")`
+// - HTTP: `GET /v1/messages/123456`
+// - gRPC: `GetMessage(message_id: "123456")`
 //
-// ## Rules for HTTP mapping
+// - HTTP: `GET /v1/users/me/messages/123456`
+// - gRPC: `GetMessage(user_id: "me" message_id: "123456")`
+//
+// Rules for HTTP mapping
 //
 // 1. Leaf request fields (recursive expansion nested messages in the request
 //    message) are classified into three categories:
@@ -224,7 +217,7 @@ message Http {
 //  request body, all
 //     fields are passed via URL path and URL query parameters.
 //
-// ### Path template syntax
+// Path template syntax
 //
 //     Template = "/" Segments [ Verb ] ;
 //     Segments = Segment { "/" Segment } ;
@@ -263,7 +256,7 @@ message Http {
 // Document](https://developers.google.com/discovery/v1/reference/apis) as
 // `{+var}`.
 //
-// ## Using gRPC API Service Configuration
+// Using gRPC API Service Configuration
 //
 // gRPC API Service Configuration (service config) is a configuration language
 // for configuring a gRPC service to become a user-facing product. The
@@ -278,15 +271,14 @@ message Http {
 // specified in the service config will override any matching transcoding
 // configuration in the proto.
 //
-// Example:
+// The following example selects a gRPC method and applies an `HttpRule` to it:
 //
 //     http:
 //       rules:
-//         # Selects a gRPC method and applies HttpRule to it.
 //         - selector: example.v1.Messaging.GetMessage
 //           get: /v1/messages/{message_id}/{sub.subfield}
 //
-// ## Special notes
+// Special notes
 //
 // When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the
 // proto to JSON conversion must follow the [proto3

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -49,7 +49,7 @@ 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
+  //  For a list of types, see [Monitored resource
   //  types](https://cloud.google.com/monitoring/api/resources)
   // and [Logging resource
   // types](https://cloud.google.com/logging/docs/api/v2/resource-list).

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -179,8 +179,13 @@ message ResourceDescriptor {
 
   // The plural name used in the resource name and permission names, such as
   // 'projects' for the resource name of 'projects/{project}' and the permission
-  // name of 'cloudresourcemanager.googleapis.com/projects.get'. It is the same
-  // concept of the `plural` field in k8s CRD spec
+  // name of 'cloudresourcemanager.googleapis.com/projects.get'. One exception
+  // to this is for Nested Collections that have stuttering names, as defined
+  // in [AIP-122](https://google.aip.dev/122#nested-collections), where the
+  // collection ID in the resource name pattern does not necessarily directly
+  // match the `plural` value.
+  //
+  // It is the same concept of the `plural` field in k8s CRD spec
   // https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
   //
   // Note: The plural form is required even for singleton resources. See

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.