codekingpro/portable-devtools

1// Copyright 2023 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19import "google/api/launch_stage.proto";20import "google/protobuf/descriptor.proto";21import "google/protobuf/duration.proto";22 23option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";24option java_multiple_files = true;25option java_outer_classname = "ClientProto";26option java_package = "com.google.api";27option objc_class_prefix = "GAPI";28 29extend google.protobuf.MethodOptions {30  // A definition of a client library method signature.31  //32  // In client libraries, each proto RPC corresponds to one or more methods33  // which the end user is able to call, and calls the underlying RPC.34  // Normally, this method receives a single argument (a struct or instance35  // corresponding to the RPC request object). Defining this field will36  // add one or more overloads providing flattened or simpler method signatures37  // in some languages.38  //39  // The fields on the method signature are provided as a comma-separated40  // string.41  //42  // For example, the proto RPC and annotation:43  //44  //   rpc CreateSubscription(CreateSubscriptionRequest)45  //       returns (Subscription) {46  //     option (google.api.method_signature) = "name,topic";47  //   }48  //49  // Would add the following Java overload (in addition to the method accepting50  // the request object):51  //52  //   public final Subscription createSubscription(String name, String topic)53  //54  // The following backwards-compatibility guidelines apply:55  //56  //   * Adding this annotation to an unannotated method is backwards57  //     compatible.58  //   * Adding this annotation to a method which already has existing59  //     method signature annotations is backwards compatible if and only if60  //     the new method signature annotation is last in the sequence.61  //   * Modifying or removing an existing method signature annotation is62  //     a breaking change.63  //   * Re-ordering existing method signature annotations is a breaking64  //     change.65  repeated string method_signature = 1051;66}67 68extend google.protobuf.ServiceOptions {69  // The hostname for this service.70  // This should be specified with no prefix or protocol.71  //72  // Example:73  //74  //   service Foo {75  //     option (google.api.default_host) = "foo.googleapi.com";76  //     ...77  //   }78  string default_host = 1049;79 80  // OAuth scopes needed for the client.81  //82  // Example:83  //84  //   service Foo {85  //     option (google.api.oauth_scopes) = \86  //       "https://www.googleapis.com/auth/cloud-platform";87  //     ...88  //   }89  //90  // If there is more than one scope, use a comma-separated string:91  //92  // Example:93  //94  //   service Foo {95  //     option (google.api.oauth_scopes) = \96  //       "https://www.googleapis.com/auth/cloud-platform,"97  //       "https://www.googleapis.com/auth/monitoring";98  //     ...99  //   }100  string oauth_scopes = 1050;101 102  // The API version of this service, which should be sent by version-aware103  // clients to the service. This allows services to abide by the schema and104  // behavior of the service at the time this API version was deployed.105  // The format of the API version must be treated as opaque by clients.106  // Services may use a format with an apparent structure, but clients must107  // not rely on this to determine components within an API version, or attempt108  // to construct other valid API versions. Note that this is for upcoming109  // functionality and may not be implemented for all services.110  //111  // Example:112  //113  //   service Foo {114  //     option (google.api.api_version) = "v1_20230821_preview";115  //   }116  string api_version = 525000001;117}118 119// Required information for every language.120message CommonLanguageSettings {121  // Link to automatically generated reference documentation.  Example:122  // https://cloud.google.com/nodejs/docs/reference/asset/latest123  string reference_docs_uri = 1 [deprecated = true];124 125  // The destination where API teams want this client library to be published.126  repeated ClientLibraryDestination destinations = 2;127}128 129// Details about how and where to publish client libraries.130message ClientLibrarySettings {131  // Version of the API to apply these settings to. This is the full protobuf132  // package for the API, ending in the version element.133  // Examples: "google.cloud.speech.v1" and "google.spanner.admin.database.v1".134  string version = 1;135 136  // Launch stage of this version of the API.137  LaunchStage launch_stage = 2;138 139  // When using transport=rest, the client request will encode enums as140  // numbers rather than strings.141  bool rest_numeric_enums = 3;142 143  // Settings for legacy Java features, supported in the Service YAML.144  JavaSettings java_settings = 21;145 146  // Settings for C++ client libraries.147  CppSettings cpp_settings = 22;148 149  // Settings for PHP client libraries.150  PhpSettings php_settings = 23;151 152  // Settings for Python client libraries.153  PythonSettings python_settings = 24;154 155  // Settings for Node client libraries.156  NodeSettings node_settings = 25;157 158  // Settings for .NET client libraries.159  DotnetSettings dotnet_settings = 26;160 161  // Settings for Ruby client libraries.162  RubySettings ruby_settings = 27;163 164  // Settings for Go client libraries.165  GoSettings go_settings = 28;166}167 168// This message configures the settings for publishing [Google Cloud Client169// libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)170// generated from the service config.171message Publishing {172  // A list of API method settings, e.g. the behavior for methods that use the173  // long-running operation pattern.174  repeated MethodSettings method_settings = 2;175 176  // Link to a *public* URI where users can report issues.  Example:177  // https://issuetracker.google.com/issues/new?component=190865&template=1161103178  string new_issue_uri = 101;179 180  // Link to product home page.  Example:181  // https://cloud.google.com/asset-inventory/docs/overview182  string documentation_uri = 102;183 184  // Used as a tracking tag when collecting data about the APIs developer185  // relations artifacts like docs, packages delivered to package managers,186  // etc.  Example: "speech".187  string api_short_name = 103;188 189  // GitHub label to apply to issues and pull requests opened for this API.190  string github_label = 104;191 192  // GitHub teams to be added to CODEOWNERS in the directory in GitHub193  // containing source code for the client libraries for this API.194  repeated string codeowner_github_teams = 105;195 196  // A prefix used in sample code when demarking regions to be included in197  // documentation.198  string doc_tag_prefix = 106;199 200  // For whom the client library is being published.201  ClientLibraryOrganization organization = 107;202 203  // Client library settings.  If the same version string appears multiple204  // times in this list, then the last one wins.  Settings from earlier205  // settings with the same version string are discarded.206  repeated ClientLibrarySettings library_settings = 109;207 208  // Optional link to proto reference documentation.  Example:209  // https://cloud.google.com/pubsub/lite/docs/reference/rpc210  string proto_reference_documentation_uri = 110;211 212  // Optional link to REST reference documentation.  Example:213  // https://cloud.google.com/pubsub/lite/docs/reference/rest214  string rest_reference_documentation_uri = 111;215}216 217// Settings for Java client libraries.218message JavaSettings {219  // The package name to use in Java. Clobbers the java_package option220  // set in the protobuf. This should be used **only** by APIs221  // who have already set the language_settings.java.package_name" field222  // in gapic.yaml. API teams should use the protobuf java_package option223  // where possible.224  //225  // Example of a YAML configuration::226  //227  //  publishing:228  //    java_settings:229  //      library_package: com.google.cloud.pubsub.v1230  string library_package = 1;231 232  // Configure the Java class name to use instead of the service's for its233  // corresponding generated GAPIC client. Keys are fully-qualified234  // service names as they appear in the protobuf (including the full235  // the language_settings.java.interface_names" field in gapic.yaml. API236  // teams should otherwise use the service name as it appears in the237  // protobuf.238  //239  // Example of a YAML configuration::240  //241  //  publishing:242  //    java_settings:243  //      service_class_names:244  //        - google.pubsub.v1.Publisher: TopicAdmin245  //        - google.pubsub.v1.Subscriber: SubscriptionAdmin246  map<string, string> service_class_names = 2;247 248  // Some settings.249  CommonLanguageSettings common = 3;250}251 252// Settings for C++ client libraries.253message CppSettings {254  // Some settings.255  CommonLanguageSettings common = 1;256}257 258// Settings for Php client libraries.259message PhpSettings {260  // Some settings.261  CommonLanguageSettings common = 1;262}263 264// Settings for Python client libraries.265message PythonSettings {266  // Some settings.267  CommonLanguageSettings common = 1;268}269 270// Settings for Node client libraries.271message NodeSettings {272  // Some settings.273  CommonLanguageSettings common = 1;274}275 276// Settings for Dotnet client libraries.277message DotnetSettings {278  // Some settings.279  CommonLanguageSettings common = 1;280 281  // Map from original service names to renamed versions.282  // This is used when the default generated types283  // would cause a naming conflict. (Neither name is284  // fully-qualified.)285  // Example: Subscriber to SubscriberServiceApi.286  map<string, string> renamed_services = 2;287 288  // Map from full resource types to the effective short name289  // for the resource. This is used when otherwise resource290  // named from different services would cause naming collisions.291  // Example entry:292  // "datalabeling.googleapis.com/Dataset": "DataLabelingDataset"293  map<string, string> renamed_resources = 3;294 295  // List of full resource types to ignore during generation.296  // This is typically used for API-specific Location resources,297  // which should be handled by the generator as if they were actually298  // the common Location resources.299  // Example entry: "documentai.googleapis.com/Location"300  repeated string ignored_resources = 4;301 302  // Namespaces which must be aliased in snippets due to303  // a known (but non-generator-predictable) naming collision304  repeated string forced_namespace_aliases = 5;305 306  // Method signatures (in the form "service.method(signature)")307  // which are provided separately, so shouldn't be generated.308  // Snippets *calling* these methods are still generated, however.309  repeated string handwritten_signatures = 6;310}311 312// Settings for Ruby client libraries.313message RubySettings {314  // Some settings.315  CommonLanguageSettings common = 1;316}317 318// Settings for Go client libraries.319message GoSettings {320  // Some settings.321  CommonLanguageSettings common = 1;322}323 324// Describes the generator configuration for a method.325message MethodSettings {326  // Describes settings to use when generating API methods that use the327  // long-running operation pattern.328  // All default values below are from those used in the client library329  // generators (e.g.330  // [Java](https://github.com/googleapis/gapic-generator-java/blob/04c2faa191a9b5a10b92392fe8482279c4404803/src/main/java/com/google/api/generator/gapic/composer/common/RetrySettingsComposer.java)).331  message LongRunning {332    // Initial delay after which the first poll request will be made.333    // Default value: 5 seconds.334    google.protobuf.Duration initial_poll_delay = 1;335 336    // Multiplier to gradually increase delay between subsequent polls until it337    // reaches max_poll_delay.338    // Default value: 1.5.339    float poll_delay_multiplier = 2;340 341    // Maximum time between two subsequent poll requests.342    // Default value: 45 seconds.343    google.protobuf.Duration max_poll_delay = 3;344 345    // Total polling timeout.346    // Default value: 5 minutes.347    google.protobuf.Duration total_poll_timeout = 4;348  }349 350  // The fully qualified name of the method, for which the options below apply.351  // This is used to find the method to apply the options.352  string selector = 1;353 354  // Describes settings to use for long-running operations when generating355  // API methods for RPCs. Complements RPCs that use the annotations in356  // google/longrunning/operations.proto.357  //358  // Example of a YAML configuration::359  //360  //  publishing:361  //    method_settings:362  //      - selector: google.cloud.speech.v2.Speech.BatchRecognize363  //        long_running:364  //          initial_poll_delay:365  //            seconds: 60 # 1 minute366  //          poll_delay_multiplier: 1.5367  //          max_poll_delay:368  //            seconds: 360 # 6 minutes369  //          total_poll_timeout:370  //             seconds: 54000 # 90 minutes371  LongRunning long_running = 2;372 373  // List of top-level fields of the request message, that should be374  // automatically populated by the client libraries based on their375  // (google.api.field_info).format. Currently supported format: UUID4.376  //377  // Example of a YAML configuration:378  //379  //  publishing:380  //    method_settings:381  //      - selector: google.example.v1.ExampleService.CreateExample382  //        auto_populated_fields:383  //        - request_id384  repeated string auto_populated_fields = 3;385}386 387// The organization for which the client libraries are being published.388// Affects the url where generated docs are published, etc.389enum ClientLibraryOrganization {390  // Not useful.391  CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0;392 393  // Google Cloud Platform Org.394  CLOUD = 1;395 396  // Ads (Advertising) Org.397  ADS = 2;398 399  // Photos Org.400  PHOTOS = 3;401 402  // Street View Org.403  STREET_VIEW = 4;404 405  // Shopping Org.406  SHOPPING = 5;407 408  // Geo Org.409  GEO = 6;410 411  // Generative AI - https://developers.generativeai.google412  GENERATIVE_AI = 7;413}414 415// To where should client libraries be published?416enum ClientLibraryDestination {417  // Client libraries will neither be generated nor published to package418  // managers.419  CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0;420 421  // Generate the client library in a repo under github.com/googleapis,422  // but don't publish it to package managers.423  GITHUB = 10;424 425  // Publish the library to package managers like nuget.org and npmjs.com.426  PACKAGE_MANAGER = 20;427}428