Skip to content

Commit 94bc991

Browse files
Google APIscopybara-github
authored andcommitted
feat: publish client batch config schema
feat: publish new error reasons docs: fix documentation formatting docs: update various comments docs: update license year PiperOrigin-RevId: 889289393
1 parent 8b491c8 commit 94bc991

31 files changed

Lines changed: 404 additions & 116 deletions

google/api/auth.proto

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -199,6 +199,7 @@ message OAuthRequirements {
199199
// The list of publicly documented OAuth scopes that are allowed access. An
200200
// OAuth token containing any of these scopes will be accepted.
201201
//
202+
//
202203
// Example:
203204
//
204205
// canonical_scopes: https://www.googleapis.com/auth/calendar,

google/api/backend.proto

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -128,6 +128,10 @@ message BackendRule {
128128
// operation. The default is no deadline.
129129
double operation_deadline = 5;
130130

131+
// Path translation specifies how to combine the backend address with the
132+
// request path in order to produce the appropriate forwarding URL for the
133+
// request. See [PathTranslation][google.api.BackendRule.PathTranslation] for
134+
// more details.
131135
PathTranslation path_translation = 6;
132136

133137
// Authentication settings used by the backend.
@@ -182,4 +186,11 @@ message BackendRule {
182186

183187
// The map between request protocol and the backend address.
184188
map<string, BackendRule> overrides_by_request_protocol = 10;
189+
190+
// The load balancing policy used for connection to the application backend.
191+
//
192+
// Defined as an arbitrary string to accomondate custom load balancing
193+
// policies supported by the underlying channel, but suggest most users use
194+
// one of the standard policies, such as the default, "RoundRobin".
195+
string load_balancing_policy = 11;
185196
}

google/api/billing.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

google/api/client.proto

Lines changed: 161 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -41,15 +41,15 @@ extend google.protobuf.MethodOptions {
4141
//
4242
// For example, the proto RPC and annotation:
4343
//
44-
// rpc CreateSubscription(CreateSubscriptionRequest)
45-
// returns (Subscription) {
46-
// option (google.api.method_signature) = "name,topic";
47-
// }
44+
// rpc CreateSubscription(CreateSubscriptionRequest)
45+
// returns (Subscription) {
46+
// option (google.api.method_signature) = "name,topic";
47+
// }
4848
//
4949
// Would add the following Java overload (in addition to the method accepting
5050
// the request object):
5151
//
52-
// public final Subscription createSubscription(String name, String topic)
52+
// public final Subscription createSubscription(String name, String topic)
5353
//
5454
// The following backwards-compatibility guidelines apply:
5555
//
@@ -71,32 +71,32 @@ extend google.protobuf.ServiceOptions {
7171
//
7272
// Example:
7373
//
74-
// service Foo {
75-
// option (google.api.default_host) = "foo.googleapi.com";
76-
// ...
77-
// }
74+
// service Foo {
75+
// option (google.api.default_host) = "foo.googleapi.com";
76+
// ...
77+
// }
7878
string default_host = 1049;
7979

8080
// OAuth scopes needed for the client.
8181
//
8282
// Example:
8383
//
84-
// service Foo {
85-
// option (google.api.oauth_scopes) = \
86-
// "https://www.googleapis.com/auth/cloud-platform";
87-
// ...
88-
// }
84+
// service Foo {
85+
// option (google.api.oauth_scopes) = \
86+
// "https://www.googleapis.com/auth/cloud-platform";
87+
// ...
88+
// }
8989
//
9090
// If there is more than one scope, use a comma-separated string:
9191
//
9292
// Example:
9393
//
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-
// }
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+
// }
100100
string oauth_scopes = 1050;
101101

102102
// The API version of this service, which should be sent by version-aware
@@ -110,9 +110,9 @@ extend google.protobuf.ServiceOptions {
110110
//
111111
// Example:
112112
//
113-
// service Foo {
114-
// option (google.api.api_version) = "v1_20230821_preview";
115-
// }
113+
// service Foo {
114+
// option (google.api.api_version) = "v1_20230821_preview";
115+
// }
116116
string api_version = 525000001;
117117
}
118118

@@ -227,9 +227,10 @@ message JavaSettings {
227227
//
228228
// Example of a YAML configuration::
229229
//
230-
// publishing:
231-
// java_settings:
232-
// library_package: com.google.cloud.pubsub.v1
230+
// publishing:
231+
// library_settings:
232+
// java_settings:
233+
// library_package: com.google.cloud.pubsub.v1
233234
string library_package = 1;
234235

235236
// Configure the Java class name to use instead of the service's for its
@@ -241,11 +242,11 @@ message JavaSettings {
241242
//
242243
// Example of a YAML configuration::
243244
//
244-
// publishing:
245-
// java_settings:
246-
// service_class_names:
247-
// - google.pubsub.v1.Publisher: TopicAdmin
248-
// - google.pubsub.v1.Subscriber: SubscriptionAdmin
245+
// publishing:
246+
// java_settings:
247+
// service_class_names:
248+
// - google.pubsub.v1.Publisher: TopicAdmin
249+
// - google.pubsub.v1.Subscriber: SubscriptionAdmin
249250
map<string, string> service_class_names = 2;
250251

251252
// Some settings.
@@ -262,6 +263,20 @@ message CppSettings {
262263
message PhpSettings {
263264
// Some settings.
264265
CommonLanguageSettings common = 1;
266+
267+
// The package name to use in Php. Clobbers the php_namespace option
268+
// set in the protobuf. This should be used **only** by APIs
269+
// who have already set the language_settings.php.package_name" field
270+
// in gapic.yaml. API teams should use the protobuf php_namespace option
271+
// where possible.
272+
//
273+
// Example of a YAML configuration::
274+
//
275+
// publishing:
276+
// library_settings:
277+
// php_settings:
278+
// library_package: Google\Cloud\PubSub\V1
279+
string library_package = 2;
265280
}
266281

267282
// Settings for Python client libraries.
@@ -353,10 +368,12 @@ message GoSettings {
353368
// service names and values are the name to be used for the service client
354369
// and call options.
355370
//
356-
// publishing:
357-
// go_settings:
358-
// renamed_services:
359-
// Publisher: TopicAdmin
371+
// Example:
372+
//
373+
// publishing:
374+
// go_settings:
375+
// renamed_services:
376+
// Publisher: TopicAdmin
360377
map<string, string> renamed_services = 2;
361378
}
362379

@@ -391,10 +408,10 @@ message MethodSettings {
391408
//
392409
// Example:
393410
//
394-
// publishing:
395-
// method_settings:
396-
// - selector: google.storage.control.v2.StorageControl.CreateFolder
397-
// # method settings for CreateFolder...
411+
// publishing:
412+
// method_settings:
413+
// - selector: google.storage.control.v2.StorageControl.CreateFolder
414+
// # method settings for CreateFolder...
398415
string selector = 1;
399416

400417
// Describes settings to use for long-running operations when generating
@@ -403,14 +420,14 @@ message MethodSettings {
403420
//
404421
// Example of a YAML configuration::
405422
//
406-
// publishing:
407-
// method_settings:
408-
// - selector: google.cloud.speech.v2.Speech.BatchRecognize
409-
// long_running:
410-
// initial_poll_delay: 60s # 1 minute
411-
// poll_delay_multiplier: 1.5
412-
// max_poll_delay: 360s # 6 minutes
413-
// total_poll_timeout: 54000s # 90 minutes
423+
// publishing:
424+
// method_settings:
425+
// - selector: google.cloud.speech.v2.Speech.BatchRecognize
426+
// long_running:
427+
// initial_poll_delay: 60s # 1 minute
428+
// poll_delay_multiplier: 1.5
429+
// max_poll_delay: 360s # 6 minutes
430+
// total_poll_timeout: 54000s # 90 minutes
414431
LongRunning long_running = 2;
415432

416433
// List of top-level fields of the request message, that should be
@@ -419,12 +436,25 @@ message MethodSettings {
419436
//
420437
// Example of a YAML configuration:
421438
//
422-
// publishing:
423-
// method_settings:
424-
// - selector: google.example.v1.ExampleService.CreateExample
425-
// auto_populated_fields:
426-
// - request_id
439+
// publishing:
440+
// method_settings:
441+
// - selector: google.example.v1.ExampleService.CreateExample
442+
// auto_populated_fields:
443+
// - request_id
427444
repeated string auto_populated_fields = 3;
445+
446+
// Batching configuration for an API method in client libraries.
447+
//
448+
// Example of a YAML configuration:
449+
//
450+
// publishing:
451+
// method_settings:
452+
// - selector: google.example.v1.ExampleService.BatchCreateExample
453+
// batching:
454+
// element_count_threshold: 1000
455+
// request_byte_threshold: 100000000
456+
// delay_threshold_millis: 10
457+
BatchingConfigProto batching = 4;
428458
}
429459

430460
// The organization for which the client libraries are being published.
@@ -484,3 +514,81 @@ message SelectiveGapicGeneration {
484514
// obfuscated identifiers, or other language idiomatic patterns.
485515
bool generate_omitted_as_internal = 2;
486516
}
517+
518+
// `BatchingConfigProto` defines the batching configuration for an API method.
519+
message BatchingConfigProto {
520+
// The thresholds which trigger a batched request to be sent.
521+
BatchingSettingsProto thresholds = 1;
522+
523+
// The request and response fields used in batching.
524+
BatchingDescriptorProto batch_descriptor = 2;
525+
}
526+
527+
// `BatchingSettingsProto` specifies a set of batching thresholds, each of
528+
// which acts as a trigger to send a batch of messages as a request. At least
529+
// one threshold must be positive nonzero.
530+
message BatchingSettingsProto {
531+
// The number of elements of a field collected into a batch which, if
532+
// exceeded, causes the batch to be sent.
533+
int32 element_count_threshold = 1;
534+
535+
// The aggregated size of the batched field which, if exceeded, causes the
536+
// batch to be sent. This size is computed by aggregating the sizes of the
537+
// request field to be batched, not of the entire request message.
538+
int64 request_byte_threshold = 2;
539+
540+
// The duration after which a batch should be sent, starting from the addition
541+
// of the first message to that batch.
542+
google.protobuf.Duration delay_threshold = 3;
543+
544+
// The maximum number of elements collected in a batch that could be accepted
545+
// by server.
546+
int32 element_count_limit = 4;
547+
548+
// The maximum size of the request that could be accepted by server.
549+
int32 request_byte_limit = 5;
550+
551+
// The maximum number of elements allowed by flow control.
552+
int32 flow_control_element_limit = 6;
553+
554+
// The maximum size of data allowed by flow control.
555+
int32 flow_control_byte_limit = 7;
556+
557+
// The behavior to take when the flow control limit is exceeded.
558+
FlowControlLimitExceededBehaviorProto flow_control_limit_exceeded_behavior =
559+
8;
560+
}
561+
562+
// The behavior to take when the flow control limit is exceeded.
563+
enum FlowControlLimitExceededBehaviorProto {
564+
// Default behavior, system-defined.
565+
UNSET_BEHAVIOR = 0;
566+
567+
// Stop operation, raise error.
568+
THROW_EXCEPTION = 1;
569+
570+
// Pause operation until limit clears.
571+
BLOCK = 2;
572+
573+
// Continue operation, disregard limit.
574+
IGNORE = 3;
575+
}
576+
577+
// `BatchingDescriptorProto` specifies the fields of the request message to be
578+
// used for batching, and, optionally, the fields of the response message to be
579+
// used for demultiplexing.
580+
message BatchingDescriptorProto {
581+
// The repeated field in the request message to be aggregated by batching.
582+
string batched_field = 1;
583+
584+
// A list of the fields in the request message. Two requests will be batched
585+
// together only if the values of every field specified in
586+
// `request_discriminator_fields` is equal between the two requests.
587+
repeated string discriminator_fields = 2;
588+
589+
// Optional. When present, indicates the field in the response message to be
590+
// used to demultiplex the response into multiple response messages, in
591+
// correspondence with the multiple request messages originally batched
592+
// together.
593+
string subresponse_field = 3;
594+
}

google/api/config_change.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

google/api/context.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

google/api/control.proto

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -32,8 +32,8 @@ option objc_class_prefix = "GAPI";
3232
// environment: servicecontrol.googleapis.com
3333
message Control {
3434
// The service controller environment to use. If empty, no control plane
35-
// feature (like quota and billing) will be enabled. The recommended value for
36-
// most services is servicecontrol.googleapis.com
35+
// features (like quota and billing) will be enabled. The recommended value
36+
// for most services is servicecontrol.googleapis.com.
3737
string environment = 1;
3838

3939
// Defines policies applying to the API methods of the service.

google/api/distribution.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

google/api/documentation.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2025 Google LLC
1+
// Copyright 2026 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.

0 commit comments

Comments
 (0)