aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/libs/googleapis-common-protos/google/api/client.proto
blob: 6d01954eee8ffecb925c3e099f990983794d22b7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

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;
option java_outer_classname = "ClientProto";
option java_package = "com.google.api";
option objc_class_prefix = "GAPI";

extend google.protobuf.MethodOptions {
  // A definition of a client library method signature.
  //
  // In client libraries, each proto RPC corresponds to one or more methods
  // which the end user is able to call, and calls the underlying RPC.
  // Normally, this method receives a single argument (a struct or instance
  // corresponding to the RPC request object). Defining this field will
  // add one or more overloads providing flattened or simpler method signatures
  // in some languages.
  //
  // The fields on the method signature are provided as a comma-separated
  // string.
  //
  // For example, the proto RPC and annotation:
  //
  //   rpc CreateSubscription(CreateSubscriptionRequest)
  //       returns (Subscription) {
  //     option (google.api.method_signature) = "name,topic";
  //   }
  //
  // Would add the following Java overload (in addition to the method accepting
  // the request object):
  //
  //   public final Subscription createSubscription(String name, String topic)
  //
  // The following backwards-compatibility guidelines apply:
  //
  //   * Adding this annotation to an unannotated method is backwards
  //     compatible.
  //   * Adding this annotation to a method which already has existing
  //     method signature annotations is backwards compatible if and only if
  //     the new method signature annotation is last in the sequence.
  //   * Modifying or removing an existing method signature annotation is
  //     a breaking change.
  //   * Re-ordering existing method signature annotations is a breaking
  //     change.
  repeated string method_signature = 1051;
}

extend google.protobuf.ServiceOptions {
  // The hostname for this service.
  // This should be specified with no prefix or protocol.
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.default_host) = "foo.googleapi.com";
  //     ...
  //   }
  string default_host = 1049;

  // OAuth scopes needed for the client.
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.oauth_scopes) = \
  //       "https://www.googleapis.com/auth/cloud-platform";
  //     ...
  //   }
  //
  // If there is more than one scope, use a comma-separated string:
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.oauth_scopes) = \
  //       "https://www.googleapis.com/auth/cloud-platform,"
  //       "https://www.googleapis.com/auth/monitoring";
  //     ...
  //   }
  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 [deprecated = true];

  // 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. This is the full protobuf
  // package for the API, ending in the version element.
  // Examples: "google.cloud.speech.v1" and "google.spanner.admin.database.v1".
  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 *public* URI where 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;

  // Optional link to proto reference documentation.  Example:
  // https://cloud.google.com/pubsub/lite/docs/reference/rpc
  string proto_reference_documentation_uri = 110;
}

// 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;

  // Map from original service names to renamed versions.
  // This is used when the default generated types
  // would cause a naming conflict. (Neither name is
  // fully-qualified.)
  // Example: Subscriber to SubscriberServiceApi.
  map<string, string> renamed_services = 2;

  // Map from full resource types to the effective short name
  // for the resource. This is used when otherwise resource
  // named from different services would cause naming collisions.
  // Example entry:
  // "datalabeling.googleapis.com/Dataset": "DataLabelingDataset"
  map<string, string> renamed_resources = 3;

  // List of full resource types to ignore during generation.
  // This is typically used for API-specific Location resources,
  // which should be handled by the generator as if they were actually
  // the common Location resources.
  // Example entry: "documentai.googleapis.com/Location"
  repeated string ignored_resources = 4;

  // Namespaces which must be aliased in snippets due to
  // a known (but non-generator-predictable) naming collision
  repeated string forced_namespace_aliases = 5;

  // Method signatures (in the form "service.method(signature)")
  // which are provided separately, so shouldn't be generated.
  // Snippets *calling* these methods are still generated, however.
  repeated string handwritten_signatures = 6;
}

// 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_settings:
  //      - selector: google.cloud.speech.v2.Speech.BatchRecognize
  //        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;

  // Shopping Org.
  SHOPPING = 5;

  // Geo Org.
  GEO = 6;

  // Generative AI - https://developers.generativeai.google
  GENERATIVE_AI = 7;
}

// 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;
}