Blame - docs/dyn/servicemanagement_v1.services.configs.html - platform/external/python/google-api-python-client

<h1><a href="servicemanagement_v1.html">Google Service Management API</a> . <a href="servicemanagement_v1.services.html">services</a> . <a href="servicemanagement_v1.services.configs.html">configs</a></h1>

76

<h2>Instance Methods</h2>

77

78

<code><a href="#create">create(serviceName=None, body, x__xgafv=None)</a></code></p>

79

<p class="firstline">Creates a new service configuration (version) for a managed service.</p>

80

81

<code><a href="#get">get(serviceName=None, configId, x__xgafv=None)</a></code></p>

82

<p class="firstline">Gets a service configuration (version) for a managed service.</p>

83

84

<code><a href="#list">list(serviceName=None, pageSize=None, pageToken=None, x__xgafv=None)</a></code></p>

85

<p class="firstline">Lists the history of the service configuration for a managed service,</p>

86

87

<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>

88

<p class="firstline">Retrieves the next page of results.</p>

89

90

<code><a href="#submit">submit(serviceName=None, body, x__xgafv=None)</a></code></p>

91

<p class="firstline">Creates a new service configuration (version) for a managed service based</p>

92

<h3>Method Details</h3>

93

94

<code class="details" id="create">create(serviceName=None, body, x__xgafv=None)</code>

95

<pre>Creates a new service configuration (version) for a managed service.

96

This method only stores the service configuration. To roll out the service

97

configuration to backend systems please call

98

CreateServiceRollout.

99

100

Args:

101

serviceName: string, The name of the service. See the [overview](/service-management/overview)

102

for naming requirements. For example: `example.googleapis.com`. (required)

103

body: object, The request body. (required)

104

The object takes the form of:

105

106

{ # `Service` is the root object of the configuration schema. It

107

# describes basic information like the name of the service and the

108

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

114

# config_version: 1

115

# name: calendar.googleapis.com

116

# title: Google Calendar API

117

# apis:

118

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

123

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

124

# service controller handles features like abuse, quota, billing, logging,

125

# monitoring, etc.

126

"environment": "A String", # The service control environment to use. If empty, no control plane

127

# feature (like quota and billing) will be enabled.

128

},

129

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

130

# by the Service.monitoring and Service.logging configurations.

131

{ # An object that describes the schema of a MonitoredResource object using a

132

# type name and a set of labels. For example, the monitored resource

133

# descriptor for Google Compute Engine VM instances has a type of

134

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

135

# `"zone"` to identify particular VM instances.

136

#

137

# Different APIs can support different monitored resource types. APIs generally

138

# provide a `list` method that returns the monitored resource descriptors used

139

# by the API.

140

"type": "A String", # Required. The monitored resource type. For example, the type

141

# `"cloudsql_database"` represents databases in Google Cloud SQL.

142

# The maximum length of this value is 256 characters.

143

"labels": [ # Required. A set of labels used to describe instances of this monitored

144

# resource type. For example, an individual Google Cloud SQL database is

145

# identified by values for the labels `"database_id"` and `"zone"`.

146

{ # A description of a label.

147

"valueType": "A String", # The type of data that can be assigned to the label.

148

"description": "A String", # A human-readable description for the label.

149

"key": "A String", # The label key.

150

},

151

],

152

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

153

# displayed in user interfaces. For example, `"Google Cloud SQL Database"`.

154

"description": "A String", # Optional. A detailed description of the monitored resource type that might

155

# be used in documentation.

156

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

157

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

158

# {type} is the value of the `type` field in this object and

159

# {project_id} is a project ID that provides API-specific context for

160

# accessing the type. APIs that do not use project information can use the

161

# resource name format `"monitoredResourceDescriptors/{type}"`.

162

},

163

],

164

"logs": [ # Defines the logs used by this service.

165

{ # A description of a log type. Example in YAML format:

166

#

167

# - name: library.googleapis.com/activity_history

168

# description: The history of borrowing and returning library items.

169

# display_name: Activity

170

# labels:

171

# - key: /customer_id

172

# description: Identifier of a library customer

173

"labels": [ # The set of labels that are available to describe a specific log entry.

174

# Runtime requests that contain labels not specified here are

175

# considered invalid.

176

{ # A description of a label.

177

"valueType": "A String", # The type of data that can be assigned to the label.

178

"description": "A String", # A human-readable description for the label.

179

"key": "A String", # The label key.

180

},

181

],

182

"displayName": "A String", # The human-readable name for this log. This information appears on

183

# the user interface and should be concise.

184

"description": "A String", # A human-readable description of this log. This information appears in

185

# the documentation and can contain details.

186

"name": "A String", # The name of the log. It must be less than 512 characters long and can

187

# include the following characters: upper- and lower-case alphanumeric

188

# characters [A-Za-z0-9], and punctuation characters including

189

# slash, underscore, hyphen, period [/_-.].

190

},

191

],

192

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

193

#

194

# A system parameter is a special kind of parameter defined by the API

195

# system, not by an individual API. It is typically mapped to an HTTP header

196

# and/or a URL query parameter. This configuration specifies which methods

197

# change the names of the system parameters.

198

"rules": [ # Define system parameters.

199

#

200

# The parameters defined here will override the default parameters

201

# implemented by the system. If this field is missing from the service

202

# config, default system parameters will be used. Default system parameters

203

# and names is implementation-dependent.

204

#

205

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

213

# - name: alt

214

# http_header: Response-Content-Type

215

#

216

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

221

# parameters:

222

# - name: api_key

223

# http_header: Api-Key1

224

# - name: api_key

225

# http_header: Api-Key2

226

#

227

# **NOTE:** All service configuration rules follow "last one wins" order.

228

{ # Define a system parameter rule mapping system parameter definitions to

229

# methods.

230

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

231

# For a given method call, only one of them should be used. If multiple

232

# names are used the behavior is implementation-dependent.

233

# If none of the specified names are present the behavior is

234

# parameter-dependent.

235

{ # Define a parameter's name and location. The parameter may be passed as either

236

# an HTTP header or a URL query parameter, and if both are passed the behavior

237

# is implementation-dependent.

238

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

239

# sensitive.

240

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

241

# and etc. It is case sensitive.

242

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

247

# methods in all APIs.

248

#

249

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

254

"rules": [ # A list of API backend rules that apply to individual API methods.

255

#

256

# **NOTE:** All service configuration rules follow "last one wins" order.

257

{ # A backend rule provides configuration for an individual API element.

258

"selector": "A String", # Selects the methods to which this rule applies.

259

#

260

# Refer to selector for syntax details.

261

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

262

# default depends on the deployment context.

263

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

268

#

269

# The example below shows how to configure monitored resources and metrics

270

# for monitoring. In the example, a monitored resource and two metrics are

271

# defined. The `library.googleapis.com/book/returned_count` metric is sent

272

# to both producer and consumer projects, whereas the

273

# `library.googleapis.com/book/overdue_count` metric is only sent to the

274

# consumer project.

275

#

276

# monitored_resources:

277

# - type: library.googleapis.com/branch

278

# labels:

279

# - key: /city

280

# description: The city where the library branch is located in.

281

# - key: /name

282

# description: The name of the branch.

283

# metrics:

284

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

289

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

294

# monitoring:

295

# producer_destinations:

296

# - monitored_resource: library.googleapis.com/branch

297

# metrics:

298

# - library.googleapis.com/book/returned_count

299

# consumer_destinations:

300

# - monitored_resource: library.googleapis.com/branch

301

# metrics:

302

# - library.googleapis.com/book/returned_count

303

# - library.googleapis.com/book/overdue_count

304

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

305

# There can be multiple producer destinations, each one must have a

306

# different monitored resource type. A metric can be used in at most

307

# one producer destination.

308

{ # Configuration of a specific monitoring destination (the producer project

309

# or the consumer project).

310

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

311

# Service.monitored_resources section.

312

"metrics": [ # Names of the metrics to report to this monitoring destination.

313

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

319

# There can be multiple consumer destinations, each one must have a

320

# different monitored resource type. A metric can be used in at most

321

# one consumer destination.

322

{ # Configuration of a specific monitoring destination (the producer project

323

# or the consumer project).

324

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

325

# Service.monitored_resources section.

326

"metrics": [ # Names of the metrics to report to this monitoring destination.

327

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

334

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

335

# by the client for tracking purpose. If empty, the server may choose to

336

# generate one instead.

337

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

338

#

339

# Example for an API targeted for external use:

340

#

341

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

347

#

348

# - selector: google.calendar.Delegate

349

# oauth:

350

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

351

"rules": [ # A list of authentication rules that apply to individual API methods.

352

#

353

# **NOTE:** All service configuration rules follow "last one wins" order.

354

{ # Authentication rules for the service.

355

#

356

# By default, if a method has any authentication requirements, every request

357

# must include a valid credential matching one of the requirements.

358

# It's an error to include more than one kind of credential in a single

359

# request.

360

#

361

# If a method doesn't have any auth requirements, request credentials will be

362

# ignored.

363

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

364

# there are scopes defined for "Read-only access to Google Calendar" and

365

# "Access to Cloud Platform". Users can consent to a scope for an application,

366

# giving it permission to access that data on their behalf.

367

#

368

# OAuth scope specifications should be fairly coarse grained; a user will need

369

# to see and understand the text description of what your scope means.

370

#

371

# In most cases: use one or at most two OAuth scopes for an entire family of

372

# products. If your product has multiple APIs, you should probably be sharing

373

# the OAuth scope across all of those APIs.

374

#

375

# When you need finer grained OAuth consent screens: talk with your product

376

# management about how developers will use them in practice.

377

#

378

# Please note that even though each of the canonical scopes is enough for a

379

# request to be accepted and passed to the backend, a request can still fail

380

# due to the backend requiring additional scopes or permissions.

381

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

382

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

387

# https://www.googleapis.com/auth/calendar.read

388

},

389

"requirements": [ # Requirements for additional authentication providers.

390

{ # User-defined authentication requirements, including support for

391

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

392

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

397

"audiences": "A String", # The list of JWT

398

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

399

# that are allowed to access. A JWT containing any of these audiences will

400

# be accepted. When this setting is absent, only JWTs with audience

401

# "https://Service_name/API_name"

402

# will be accepted. For example, if no audiences are in the setting,

403

# LibraryService API will only accept JWTs with the following audience

404

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

409

# bookstore_web.apps.googleusercontent.com

410

},

411

],

412

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. If quota is enabled, an

413

# API key is required for such request to pass the quota check.

414

"selector": "A String", # Selects the methods to which this rule applies.

415

#

416

# Refer to selector for syntax details.

417

},

418

],

419

"providers": [ # Defines a set of authentication providers that a service supports.

420

{ # Configuration for an anthentication provider, including support for

421

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

422

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

423

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

424

# Optional if the key set document:

425

# - can be retrieved from

426

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

427

# of the issuer.

428

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

429

#

430

# Example: https://www.googleapis.com/oauth2/v1/certs

431

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

432

# `AuthRequirement.provider_id`.

433

#

434

# Example: "bookstore_auth".

435

"issuer": "A String", # Identifies the principal that issued the JWT. See

436

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

437

# Usually a URL or an email address.

438

#

439

# Example: https://securetoken.google.com

440

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

445

"rules": [ # A list of usage rules that apply to individual API methods.

446

#

447

# **NOTE:** All service configuration rules follow "last one wins" order.

448

{ # Usage configuration rules for the service.

449

#

450

# NOTE: Under development.

451

#

452

#

453

# Use this rule to configure unregistered calls for the service. Unregistered

454

# calls are calls that do not contain consumer project identity.

455

# (Example: calls that do not contain an API key).

456

# By default, API methods do not allow unregistered calls, and each method call

457

# must be identified by a consumer project identity. Use this rule to

458

# allow/disallow unregistered calls.

459

#

460

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

466

#

467

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

472

# allow_unregistered_calls: true

473

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

474

# methods in all APIs.

475

#

476

# Refer to selector for syntax details.

477

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

478

},

479

],

480

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

481

# service. Each requirement is of the form <service.name>/<requirement-id>;

482

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

487

# influence interpretation of the configuration, for example, to

488

# determine defaults. This is documented together with applicable

489

# options. The current default for the config version itself is `3`.

490

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

491

# Members of this project can manage the service configuration,

492

# manage consumption of the service, etc.

493

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

494

# HttpRule, each specifying the mapping of an RPC method

495

# to one or more HTTP REST API methods.

496

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

497

#

498

# **NOTE:** All service configuration rules follow "last one wins" order.

499

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

500

# REST APIs. The mapping determines what portions of the request

501

# message are populated from the path, query parameters, or body of

502

# the HTTP request. The mapping is typically specified as an

503

# `google.api.http` annotation, see "google/api/annotations.proto"

504

# for details.

505

#

506

# The mapping consists of a field specifying the path template and

507

# method kind. The path template can refer to fields in the request

508

# message, as in the example below which describes a REST GET

509

# operation on a resource collection of messages:

510

#

511

# ```proto

512

# service Messaging {

513

# rpc GetMessage(GetMessageRequest) returns (Message) {

514

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

515

# }

516

# }

517

# message GetMessageRequest {

518

# message SubMessage {

519

# string subfield = 1;

520

# }

521

# string message_id = 1; // mapped to the URL

522

# SubMessage sub = 2; // `sub.subfield` is url-mapped

523

# }

524

# message Message {

525

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

530

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

535

#

536

# In general, not only fields but also field paths can be referenced

537

# from a path pattern. Fields mapped to the path pattern cannot be

538

# repeated and must have a primitive (non-message) type.

539

#

540

# Any fields in the request message which are not bound by the path

541

# pattern automatically become (optional) HTTP query

542

# parameters. Assume the following definition of the request message:

543

#

544

# ```proto

545

# message GetMessageRequest {

546

# message SubMessage {

547

# string subfield = 1;

548

# }

549

# string message_id = 1; // mapped to the URL

550

# int64 revision = 2; // becomes a parameter

551

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

560

#

561

# Note that fields which are mapped to HTTP parameters must have a

562

# primitive type or a repeated primitive type. Message types are not

563

# allowed. In the case of a repeated type, the parameter can be

564

# repeated in the URL, as in `...?param=A&param=B`.

565

#

566

# For HTTP method kinds which allow a request body, the `body` field

567

# specifies the mapping. Consider a REST update method on the

568

# message resource collection:

569

#

570

# ```proto

571

# service Messaging {

572

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

573

# option (google.api.http) = {

574

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

580

# string message_id = 1; // mapped to the URL

581

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

586

# representation of the JSON in the request body is determined by

587

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

592

#

593

# The special name `*` can be used in the body mapping to define that

594

# every field not bound by the path template should be mapped to the

595

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

600

# rpc UpdateMessage(Message) returns (Message) {

601

# option (google.api.http) = {

602

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

618

#

619

# Note that when using `*` in the body mapping, it is not possible to

620

# have HTTP parameters, as all fields not bound by the path end in

621

# the body. This makes this option more rarely used in practice of

622

# defining REST APIs. The common usage of `*` is in custom methods

623

# which don't use the URL at all for transferring data.

624

#

625

# It is possible to define multiple HTTP methods for one RPC by using

626

# the `additional_bindings` option. Example:

627

#

628

# ```proto

629

# service Messaging {

630

# rpc GetMessage(GetMessageRequest) returns (Message) {

631

# option (google.api.http) = {

632

# get: "/v1/messages/{message_id}"

633

# additional_bindings {

634

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

640

# string message_id = 1;

641

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

651

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

652

#

653

# # Rules for HTTP mapping

654

#

655

# The rules for mapping HTTP path, query parameters, and body fields

656

# to the request message are as follows:

657

#

658

# 1. The `body` field specifies either `*` or a field path, or is

659

# omitted. If omitted, it assumes there is no HTTP body.

660

# 2. Leaf fields (recursive expansion of nested messages in the

661

# request) can be classified into three types:

662

# (a) Matched in the URL template.

663

# (b) Covered by body (if body is `*`, everything except (a) fields;

664

# else everything under the body field)

665

# (c) All other fields.

666

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

667

# 4. Any body sent with an HTTP request can contain only (b) fields.

668

#

669

# The syntax of the path template is as follows:

670

#

671

# Template = "/" Segments [ Verb ] ;

672

# Segments = Segment { "/" Segment } ;

673

# Segment = "*" | "**" | LITERAL | Variable ;

674

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

675

# FieldPath = IDENT { "." IDENT } ;

676

# Verb = ":" LITERAL ;

677

#

678

# The syntax `*` matches a single path segment. It follows the semantics of

679

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

680

# Expansion.

681

#

682

# The syntax `**` matches zero or more path segments. It follows the semantics

683

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

684

# Expansion.

685

#

686

# The syntax `LITERAL` matches literal text in the URL path.

687

#

688

# The syntax `Variable` matches the entire path as specified by its template;

689

# this nested template must not contain further variables. If a variable

690

# matches a single path segment, its template may be omitted, e.g. `{var}`

691

# is equivalent to `{var=*}`.

692

#

693

# NOTE: the field paths in variables and in the `body` must not refer to

694

# repeated fields or map fields.

695

#

696

# Use CustomHttpPattern to specify any HTTP method that is not included in the

697

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

698

# a given URL path rule. The wild-card rule is useful for services that provide

699

# content to Web (HTML) clients.

700

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

701

# `*` for mapping all fields not captured by the path pattern to the HTTP

702

# body. NOTE: the referred field must not be a repeated field and must be

703

# present at the top-level of response message type.

704

"get": "A String", # Used for listing and getting information about resources.

705

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

706

# [][google.bytestream.RestByteStream] as an API to your

707

# configuration.

708

# [][google.bytestream.RestByteStream] as an API to your

709

# configuration.

710

"enabled": True or False, # Whether download is enabled.

711

},

712

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

713

# not contain an `additional_bindings` field themselves (that is,

714

# the nesting may only be one level deep).

715

# Object with schema name: HttpRule

716

],

717

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

718

# [][google.bytestream.RestByteStream] as an API to your

719

# configuration.

720

# [][google.bytestream.RestByteStream] as an API to your

721

# configuration.

722

"enabled": True or False, # Whether upload is enabled.

723

},

724

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

725

"path": "A String", # The path matched by this custom verb.

726

"kind": "A String", # The name of this custom HTTP verb.

727

},

728

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

729

# response. Other response fields are ignored. This field is optional. When

730

# not set, the response message will be used as HTTP body of response.

731

# NOTE: the referred field must be not a repeated field and must be present

732

# at the top-level of response message type.

733

"put": "A String", # Used for updating a resource.

734

"patch": "A String", # Used for updating a resource.

735

"post": "A String", # Used for creating a resource.

736

"selector": "A String", # Selects methods to which this rule applies.

737

#

738

# Refer to selector for syntax details.

739

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

744

# of the google.protobuf.Api needs to be provided by the configuration

745

# author, as the remaining fields will be derived from the IDL during the

746

# normalization process. It is an error to specify an API interface here

747

# which cannot be resolved against the associated IDL files.

748

{ # Api is a light-weight descriptor for a protocol buffer service.

749

"methods": [ # The methods of this api, in unspecified order.

750

{ # Method represents a method of an api.

751

"name": "A String", # The simple name of this method.

752

"requestStreaming": True or False, # If true, the request is streamed.

753

"responseTypeUrl": "A String", # The URL of the output message type.

754

"requestTypeUrl": "A String", # A URL of the input message type.

755

"responseStreaming": True or False, # If true, the response is streamed.

756

"syntax": "A String", # The source syntax of this method.

757

"options": [ # Any metadata attached to the method.

758

{ # A protocol buffer option, which can be attached to a message, field,

759

# enumeration, etc.

760

"name": "A String", # The option's name. For example, `"java_package"`.

761

"value": { # The option's value. For example, `"com.google.protobuf"`.

762

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

769

# message.

770

# protobuf element, like the file in which it is defined.

771

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

772

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

773

},

774

"mixins": [ # Included APIs. See Mixin.

775

{ # Declares an API to be included in this API. The including API must

776

# redeclare all the methods from the included API, but documentation

777

# and options are inherited as follows:

778

#

779

# - If after comment and whitespace stripping, the documentation

780

# string of the redeclared method is empty, it will be inherited

781

# from the original method.

782

#

783

# - Each annotation belonging to the service config (http,

784

# visibility) which is not set in the redeclared method will be

785

# inherited.

786

#

787

# - If an http annotation is inherited, the path pattern will be

788

# modified as follows. Any version prefix will be replaced by the

789

# version of the including API plus the root path if specified.

790

#

791

# Example of a simple mixin:

792

#

793

# package google.acl.v1;

794

# service AccessControl {

795

# // Get the underlying ACL object.

796

# rpc GetAcl(GetAclRequest) returns (Acl) {

797

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

802

# service Storage {

803

# // rpc GetAcl(GetAclRequest) returns (Acl);

804

#

805

# // Get a data record.

806

# rpc GetData(GetDataRequest) returns (Data) {

807

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

812

#

813

# apis:

814

# - name: google.storage.v2.Storage

815

# mixins:

816

# - name: google.acl.v1.AccessControl

817

#

818

# The mixin construct implies that all methods in `AccessControl` are

819

# also declared with same name and request/response types in

820

# `Storage`. A documentation generator or annotation processor will

821

# see the effective `Storage.GetAcl` method after inherting

822

# documentation and annotations as follows:

823

#

824

# service Storage {

825

# // Get the underlying ACL object.

826

# rpc GetAcl(GetAclRequest) returns (Acl) {

827

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

833

#

834

# If the `root` field in the mixin is specified, it should be a

835

# relative path under which inherited HTTP paths are placed. Example:

836

#

837

# apis:

838

# - name: google.storage.v2.Storage

839

# mixins:

840

# - name: google.acl.v1.AccessControl

841

# root: acls

842

#

843

# This implies the following inherited HTTP annotation:

844

#

845

# service Storage {

846

# // Get the underlying ACL object.

847

# rpc GetAcl(GetAclRequest) returns (Acl) {

848

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

853

# are rooted.

854

"name": "A String", # The fully qualified name of the API which is included.

855

},

856

],

857

"syntax": "A String", # The source syntax of the service.

858

"version": "A String", # A version string for this api. If specified, must have the form

859

# `major-version.minor-version`, as in `1.10`. If the minor version

860

# is omitted, it defaults to zero. If the entire version field is

861

# empty, the major version is derived from the package name, as

862

# outlined below. If the field is not empty, the version in the

863

# package name will be verified to be consistent with what is

864

# provided here.

865

#

866

# The versioning schema uses [semantic

867

# versioning](http://semver.org) where the major version number

868

# indicates a breaking change and the minor version an additive,

869

# non-breaking change. Both version numbers are signals to users

870

# what to expect from different versions, and should be carefully

871

# chosen based on the product plan.

872

#

873

# The major version is also reflected in the package name of the

874

# API, which must end in `v<major-version>`, as in

875

# `google.feature.v1`. For major versions 0 and 1, the suffix can

876

# be omitted. Zero major versions must only be used for

877

# experimental, none-GA apis.

878

"options": [ # Any metadata attached to the API.

879

{ # A protocol buffer option, which can be attached to a message, field,

880

# enumeration, etc.

881

"name": "A String", # The option's name. For example, `"java_package"`.

882

"value": { # The option's value. For example, `"com.google.protobuf"`.

883

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

888

# followed by the api's simple name.

889

},

890

],

891

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

892

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

900

# - google.foo.v1.AnotherError

901

"rules": [ # The list of custom error rules that apply to individual API messages.

902

#

903

# **NOTE:** All service configuration rules follow "last one wins" order.

904

{ # A custom error rule.

905

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

906

# objects of this type will be filtered when they appear in error payload.

907

"selector": "A String", # Selects messages to which this rule applies.

908

#

909

# Refer to selector for syntax details.

910

},

911

],

912

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

917

# elements. Restrictions are specified using visibility labels

918

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

919

#

920

# Users and projects can have access to more than one visibility label. The

921

# effective visibility for multiple labels is the union of each label's

922

# elements, plus any unrestricted elements.

923

#

924

# If an element and its parents have no restrictions, visibility is

925

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

932

# restriction: TRUSTED_TESTER

933

# - selector: google.calendar.Calendar.Delegate

934

# restriction: GOOGLE_INTERNAL

935

#

936

# Here, all methods are publicly visible except for the restricted methods

937

# EnhancedSearch and Delegate.

938

"rules": [ # A list of visibility rules that apply to individual API elements.

939

#

940

# **NOTE:** All service configuration rules follow "last one wins" order.

941

{ # A visibility rule provides visibility configuration for an individual API

942

# element.

943

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

944

# visibility to the element.

945

#

946

# If a rule has multiple labels, removing one of the labels but not all of

947

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

954

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

955

#

956

# Removing GOOGLE_INTERNAL from this restriction will break clients that

957

# rely on this method and only had access to it through GOOGLE_INTERNAL.

958

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

959

#

960

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

965

{ # Defines a metric type and its schema.

966

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

967

# Use sentence case without an ending period, for example "Request count".

968

"description": "A String", # A detailed description of the metric, which can be used in documentation.

969

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

970

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

971

"labels": [ # The set of labels that can be used to describe a specific instance of this

972

# metric type. For example, the

973

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

974

# has a label, `loadbalanced`, that specifies whether the traffic was

975

# received through a load balanced IP address.

976

{ # A description of a label.

977

"valueType": "A String", # The type of data that can be assigned to the label.

978

"description": "A String", # A human-readable description for the label.

979

"key": "A String", # The label key.

980

},

981

],

982

"type": "A String", # The metric type including a DNS name prefix, for example

983

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

984

# should use a natural hierarchical grouping such as the following:

985

#

986

# compute.googleapis.com/instance/cpu/utilization

987

# compute.googleapis.com/instance/disk/read_ops_count

988

# compute.googleapis.com/instance/network/received_bytes_count

989

#

990

# Note that if the metric type changes, the monitoring data will be

991

# discontinued, and anything depends on it will break, such as monitoring

992

# dashboards, alerting rules and quota limits. Therefore, once a metric has

993

# been published, its type should be immutable.

994

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

995

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

996

# supported units are a subset of [The Unified Code for Units of

997

# Measure](http://unitsofmeasure.org/ucum.html) standard:

998

#

999

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

1014

# * `P` peta (10**15)

1015

# * `E` exa (10**18)

1016

# * `Z` zetta (10**21)

1017

# * `Y` yotta (10**24)

1018

# * `m` milli (10**-3)

1019

# * `u` micro (10**-6)

1020

# * `n` nano (10**-9)

1021

# * `p` pico (10**-12)

1022

# * `f` femto (10**-15)

1023

# * `a` atto (10**-18)

1024

# * `z` zepto (10**-21)

1025

# * `y` yocto (10**-24)

1026

# * `Ki` kibi (2**10)

1027

# * `Mi` mebi (2**20)

1028

# * `Gi` gibi (2**30)

1029

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

1034

#

1035

# The grammar also includes these connectors:

1036

#

1037

# * `/` division (as an infix operator, e.g. `1/s`).

1038

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

1039

#

1040

# The grammar for a unit is as follows:

1041

#

1042

# Expression = Component { "." Component } { "/" Component } ;

1043

#

1044

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

1054

# equivalent to `1` if it is used alone. For examples,

1055

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

1056

# * `NAME` is a sequence of non-blank printable ASCII characters not

1057

# containing '{' or '}'.

1058

"name": "A String", # Resource name. The format of the name may vary between different

1059

# implementations. For examples:

1060

#

1061

# projects/{project_id}/metricDescriptors/{type=**}

1062

# metricDescriptors/{type=**}

1063

},

1064

],

1065

"enums": [ # A list of all enum types included in this API service. Enums

1066

# referenced directly or indirectly by the `apis` are automatically

1067

# included. Enums which are not referenced but shall be included

1068

# should be listed here by name. Example:

1069

#

1070

# enums:

1071

# - name: google.someapi.v1.SomeEnum

1072

{ # Enum type definition.

1073

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1074

# protobuf element, like the file in which it is defined.

1075

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1076

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1077

},

1078

"enumvalue": [ # Enum value definitions.

1079

{ # Enum value definition.

1080

"number": 42, # Enum value number.

1081

"options": [ # Protocol buffer options.

1082

{ # A protocol buffer option, which can be attached to a message, field,

1083

# enumeration, etc.

1084

"name": "A String", # The option's name. For example, `"java_package"`.

1085

"value": { # The option's value. For example, `"com.google.protobuf"`.

1086

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

1091

},

1092

],

1093

"options": [ # Protocol buffer options.

1094

{ # A protocol buffer option, which can be attached to a message, field,

1095

# enumeration, etc.

1096

"name": "A String", # The option's name. For example, `"java_package"`.

1097

"value": { # The option's value. For example, `"com.google.protobuf"`.

1098

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

1103

"syntax": "A String", # The source syntax.

1104

},

1105

],

1106

"types": [ # A list of all proto message types included in this API service.

1107

# Types referenced directly or indirectly by the `apis` are

1108

# automatically included. Messages which are not referenced but

1109

# shall be included, such as types used by the `google.protobuf.Any` type,

1110

# should be listed here by name. Example:

1111

#

1112

# types:

1113

# - name: google.protobuf.Int32

1114

{ # A protocol buffer message type.

1115

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1116

"A String",

1117

],

1118

"name": "A String", # The fully qualified message name.

1119

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1120

# protobuf element, like the file in which it is defined.

1121

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1122

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1123

},

1124

"syntax": "A String", # The source syntax.

1125

"fields": [ # The list of fields.

1126

{ # A single field of a message type.

1127

"kind": "A String", # The field type.

1128

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1129

# types. The first type has index 1; zero means the type is not in the list.

1130

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1131

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1132

"name": "A String", # The field name.

1133

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1134

"jsonName": "A String", # The field JSON name.

1135

"number": 42, # The field number.

1136

"cardinality": "A String", # The field cardinality.

1137

"options": [ # The protocol buffer options.

1138

{ # A protocol buffer option, which can be attached to a message, field,

1139

# enumeration, etc.

1140

"name": "A String", # The option's name. For example, `"java_package"`.

1141

"value": { # The option's value. For example, `"com.google.protobuf"`.

1142

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1147

},

1148

],

1149

"options": [ # The protocol buffer options.

1150

{ # A protocol buffer option, which can be attached to a message, field,

1151

# enumeration, etc.

1152

"name": "A String", # The option's name. For example, `"java_package"`.

1153

"value": { # The option's value. For example, `"com.google.protobuf"`.

1154

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

1161

#

1162

# The following example shows how to configure logs to be sent to the

1163

# producer and consumer projects. In the example,

1164

# the `library.googleapis.com/activity_history` log is

1165

# sent to both the producer and consumer projects, whereas

1166

# the `library.googleapis.com/purchase_history` log is only sent to the

1167

# producer project:

1168

#

1169

# monitored_resources:

1170

# - type: library.googleapis.com/branch

1171

# labels:

1172

# - key: /city

1173

# description: The city where the library branch is located in.

1174

# - key: /name

1175

# description: The name of the branch.

1176

# logs:

1177

# - name: library.googleapis.com/activity_history

1178

# labels:

1179

# - key: /customer_id

1180

# - name: library.googleapis.com/purchase_history

1181

# logging:

1182

# producer_destinations:

1183

# - monitored_resource: library.googleapis.com/branch

1184

# logs:

1185

# - library.googleapis.com/activity_history

1186

# - library.googleapis.com/purchase_history

1187

# consumer_destinations:

1188

# - monitored_resource: library.googleapis.com/branch

1189

# logs:

1190

# - library.googleapis.com/activity_history

1191

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

1192

# There can be multiple producer destinations, each one must have a

1193

# different monitored resource type. A log can be used in at most

1194

# one producer destination.

1195

{ # Configuration of a specific logging destination (the producer project

1196

# or the consumer project).

1197

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1198

# Service.monitored_resources section.

1199

"logs": [ # Names of the logs to be sent to this destination. Each name must

1200

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

1206

# There can be multiple consumer destinations, each one must have a

1207

# different monitored resource type. A log can be used in at most

1208

# one consumer destination.

1209

{ # Configuration of a specific logging destination (the producer project

1210

# or the consumer project).

1211

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1212

# Service.monitored_resources section.

1213

"logs": [ # Names of the logs to be sent to this destination. Each name must

1214

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

1221

# e.g. `calendar.googleapis.com`.

1222

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

1223

#

1224

# Example:

1225

# <pre><code>documentation:

1226

# summary: >

1227

# The Google Calendar API gives access

1228

# to most calendar features.

1229

# pages:

1230

# - name: Overview

1231

# content: (== include google/foo/overview.md ==)

1232

# - name: Tutorial

1233

# content: (== include google/foo/tutorial.md ==)

1234

# subpages;

1235

# - name: Java

1236

# content: (== include google/foo/tutorial_java.md ==)

1237

# rules:

1238

# - selector: google.calendar.Calendar.Get

1239

# description: >

1240

# ...

1241

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1246

# standard markdown features, definition lists, tables and fenced

1247

# code blocks are supported. Section headers can be provided and are

1248

# interpreted relative to the section nesting of the context where

1249

# a documentation fragment is embedded.

1250

#

1251

# Documentation from the IDL is merged with documentation defined

1252

# via the config at normalization time, where documentation provided

1253

# by config rules overrides IDL provided.

1254

#

1255

# A number of constructs specific to the API platform are supported

1256

# in documentation text.

1257

#

1258

# In order to reference a proto element, the following

1259

# notation can be used:

1260

# <pre><code>[fully.qualified.proto.name][]</code></pre>

1261

# To override the display text used for the link, this can be used:

1262

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

1263

# Text can be excluded from doc using the following notation:

1264

# <pre><code>(-- internal comment --)</code></pre>

1265

# Comments can be made conditional using a visibility label. The below

1266

# text will be only rendered if the `BETA` label is available:

1267

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

1268

# A few directives are available in documentation. Note that

1269

# directives must appear on a single line to be properly

1270

# identified. The `include` directive includes a markdown file from

1271

# an external source:

1272

# <pre><code>(== include path/to/file ==)</code></pre>

1273

# The `resource_for` directive marks a message to be the resource of

1274

# a collection in REST view. If it is not specified, tools attempt

1275

# to infer the resource from the operations in a collection:

1276

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

1277

# The directive `suppress_warning` does not directly affect documentation

1278

# and is documented together with service config validation.

1279

"rules": [ # A list of documentation rules that apply to individual API elements.

1280

#

1281

# **NOTE:** All service configuration rules follow "last one wins" order.

1282

{ # A documentation rule provides information about individual API elements.

1283

"description": "A String", # Description of the selected API(s).

1284

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

1285

# element is marked as `deprecated`.

1286

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

1287

# qualified name of the element which may end in "*", indicating a wildcard.

1288

# Wildcards are only allowed at the end and for a whole component of the

1289

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

1290

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

1295

# <pre><code>documentation:

1296

# summary: ...

1297

# overview: (== include overview.md ==)

1298

# </code></pre>

1299

# This is a shortcut for the following declaration (using pages style):

1300

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

1305

# </code></pre>

1306

# Note: you cannot specify both `overview` field and `pages` field.

1307

"summary": "A String", # A short summary of what the service does. Can only be provided by

1308

# plain text.

1309

"pages": [ # The top level pages for the documentation set.

1310

{ # Represents a documentation page. A page can contain subpages to represent

1311

# nested documentation set structure.

1312

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

1313

# to include content from a Markdown file.

1314

"subpages": [ # Subpages of this page. The order of subpages specified here will be

1315

# honored in the generated docset.

1316

# Object with schema name: Page

1317

],

1318

"name": "A String", # The name of the page. It will be used as an identity of the page to

1319

# generate URI of the page, text of the link to this page in navigation,

1320

# etc. The full page name (start from the root page name to this page

1321

# concatenated with `.`) can be used as reference to the page in your

1322

# documentation. For example:

1323

# <pre><code>pages:

1324

# - name: Tutorial

1325

# content: (== include tutorial.md ==)

1326

# subpages:

1327

# - name: Java

1328

# content: (== include tutorial_java.md ==)

1329

# </code></pre>

1330

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

1335

},

1336

"systemTypes": [ # A list of all proto message types included in this API service.

1337

# It serves similar purpose as [google.api.Service.types], except that

1338

# these types are not needed by user-defined APIs. Therefore, they will not

1339

# show up in the generated discovery doc. This field should only be used

1340

# to define system APIs in ESF.

1341

{ # A protocol buffer message type.

1342

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1343

"A String",

1344

],

1345

"name": "A String", # The fully qualified message name.

1346

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1347

# protobuf element, like the file in which it is defined.

1348

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1349

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1350

},

1351

"syntax": "A String", # The source syntax.

1352

"fields": [ # The list of fields.

1353

{ # A single field of a message type.

1354

"kind": "A String", # The field type.

1355

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1356

# types. The first type has index 1; zero means the type is not in the list.

1357

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1358

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1359

"name": "A String", # The field name.

1360

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1361

"jsonName": "A String", # The field JSON name.

1362

"number": 42, # The field number.

1363

"cardinality": "A String", # The field cardinality.

1364

"options": [ # The protocol buffer options.

1365

{ # A protocol buffer option, which can be attached to a message, field,

1366

# enumeration, etc.

1367

"name": "A String", # The option's name. For example, `"java_package"`.

1368

"value": { # The option's value. For example, `"com.google.protobuf"`.

1369

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1374

},

1375

],

1376

"options": [ # The protocol buffer options.

1377

{ # A protocol buffer option, which can be attached to a message, field,

1378

# enumeration, etc.

1379

"name": "A String", # The option's name. For example, `"java_package"`.

1380

"value": { # The option's value. For example, `"com.google.protobuf"`.

1381

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

1396

# - google.rpc.context.OriginContext

1397

#

1398

# The above specifies that all methods in the API request

1399

# `google.rpc.context.ProjectContext` and

1400

# `google.rpc.context.OriginContext`.

1401

#

1402

# Available context types are defined in package

1403

# `google.rpc.context`.

1404

"rules": [ # A list of RPC context rules that apply to individual API methods.

1405

#

1406

# **NOTE:** All service configuration rules follow "last one wins" order.

1407

{ # A context rule provides information about the context for an individual API

1408

# element.

1409

"provided": [ # A list of full type names of provided contexts.

1410

"A String",

1411

],

1412

"requested": [ # A list of full type names of requested contexts.

1413

"A String",

1414

],

1415

"selector": "A String", # Selects the methods to which this rule applies.

1416

#

1417

# Refer to selector for syntax details.

},

],

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1430

1431

{ # `Service` is the root object of the configuration schema. It

1432

# describes basic information like the name of the service and the

1433

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

1439

# config_version: 1

1440

# name: calendar.googleapis.com

1441

# title: Google Calendar API

1442

# apis:

1443

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

1448

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

1449

# service controller handles features like abuse, quota, billing, logging,

1450

# monitoring, etc.

1451

"environment": "A String", # The service control environment to use. If empty, no control plane

1452

# feature (like quota and billing) will be enabled.

1453

},

1454

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

1455

# by the Service.monitoring and Service.logging configurations.

1456

{ # An object that describes the schema of a MonitoredResource object using a

1457

# type name and a set of labels. For example, the monitored resource

1458

# descriptor for Google Compute Engine VM instances has a type of

1459

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

1460

# `"zone"` to identify particular VM instances.

1461

#

1462

# Different APIs can support different monitored resource types. APIs generally

1463

# provide a `list` method that returns the monitored resource descriptors used

1464

# by the API.

1465

"type": "A String", # Required. The monitored resource type. For example, the type

1466

# `"cloudsql_database"` represents databases in Google Cloud SQL.

1467

# The maximum length of this value is 256 characters.

1468

"labels": [ # Required. A set of labels used to describe instances of this monitored

1469

# resource type. For example, an individual Google Cloud SQL database is

1470

# identified by values for the labels `"database_id"` and `"zone"`.

1471

{ # A description of a label.

1472

"valueType": "A String", # The type of data that can be assigned to the label.

1473

"description": "A String", # A human-readable description for the label.

1474

"key": "A String", # The label key.

1475

},

1476

],

1477

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

1478

# displayed in user interfaces. For example, `"Google Cloud SQL Database"`.

1479

"description": "A String", # Optional. A detailed description of the monitored resource type that might

1480

# be used in documentation.

1481

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

1482

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

1483

# {type} is the value of the `type` field in this object and

1484

# {project_id} is a project ID that provides API-specific context for

1485

# accessing the type. APIs that do not use project information can use the

1486

# resource name format `"monitoredResourceDescriptors/{type}"`.

1487

},

1488

],

1489

"logs": [ # Defines the logs used by this service.

1490

{ # A description of a log type. Example in YAML format:

1491

#

1492

# - name: library.googleapis.com/activity_history

1493

# description: The history of borrowing and returning library items.

1494

# display_name: Activity

1495

# labels:

1496

# - key: /customer_id

1497

# description: Identifier of a library customer

1498

"labels": [ # The set of labels that are available to describe a specific log entry.

1499

# Runtime requests that contain labels not specified here are

1500

# considered invalid.

1501

{ # A description of a label.

1502

"valueType": "A String", # The type of data that can be assigned to the label.

1503

"description": "A String", # A human-readable description for the label.

1504

"key": "A String", # The label key.

1505

},

1506

],

1507

"displayName": "A String", # The human-readable name for this log. This information appears on

1508

# the user interface and should be concise.

1509

"description": "A String", # A human-readable description of this log. This information appears in

1510

# the documentation and can contain details.

1511

"name": "A String", # The name of the log. It must be less than 512 characters long and can

1512

# include the following characters: upper- and lower-case alphanumeric

1513

# characters [A-Za-z0-9], and punctuation characters including

1514

# slash, underscore, hyphen, period [/_-.].

1515

},

1516

],

1517

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

1518

#

1519

# A system parameter is a special kind of parameter defined by the API

1520

# system, not by an individual API. It is typically mapped to an HTTP header

1521

# and/or a URL query parameter. This configuration specifies which methods

1522

# change the names of the system parameters.

1523

"rules": [ # Define system parameters.

1524

#

1525

# The parameters defined here will override the default parameters

1526

# implemented by the system. If this field is missing from the service

1527

# config, default system parameters will be used. Default system parameters

1528

# and names is implementation-dependent.

1529

#

1530

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1538

# - name: alt

1539

# http_header: Response-Content-Type

1540

#

1541

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1546

# parameters:

1547

# - name: api_key

1548

# http_header: Api-Key1

1549

# - name: api_key

1550

# http_header: Api-Key2

1551

#

1552

# **NOTE:** All service configuration rules follow "last one wins" order.

1553

{ # Define a system parameter rule mapping system parameter definitions to

1554

# methods.

1555

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

1556

# For a given method call, only one of them should be used. If multiple

1557

# names are used the behavior is implementation-dependent.

1558

# If none of the specified names are present the behavior is

1559

# parameter-dependent.

1560

{ # Define a parameter's name and location. The parameter may be passed as either

1561

# an HTTP header or a URL query parameter, and if both are passed the behavior

1562

# is implementation-dependent.

1563

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

1564

# sensitive.

1565

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

1566

# and etc. It is case sensitive.

1567

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1572

# methods in all APIs.

1573

#

1574

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

1579

"rules": [ # A list of API backend rules that apply to individual API methods.

1580

#

1581

# **NOTE:** All service configuration rules follow "last one wins" order.

1582

{ # A backend rule provides configuration for an individual API element.

1583

"selector": "A String", # Selects the methods to which this rule applies.

1584

#

1585

# Refer to selector for syntax details.

1586

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

1587

# default depends on the deployment context.

1588

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

1593

#

1594

# The example below shows how to configure monitored resources and metrics

1595

# for monitoring. In the example, a monitored resource and two metrics are

1596

# defined. The `library.googleapis.com/book/returned_count` metric is sent

1597

# to both producer and consumer projects, whereas the

1598

# `library.googleapis.com/book/overdue_count` metric is only sent to the

1599

# consumer project.

1600

#

1601

# monitored_resources:

1602

# - type: library.googleapis.com/branch

1603

# labels:

1604

# - key: /city

1605

# description: The city where the library branch is located in.

1606

# - key: /name

1607

# description: The name of the branch.

1608

# metrics:

1609

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1614

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1619

# monitoring:

1620

# producer_destinations:

1621

# - monitored_resource: library.googleapis.com/branch

1622

# metrics:

1623

# - library.googleapis.com/book/returned_count

1624

# consumer_destinations:

1625

# - monitored_resource: library.googleapis.com/branch

1626

# metrics:

1627

# - library.googleapis.com/book/returned_count

1628

# - library.googleapis.com/book/overdue_count

1629

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

1630

# There can be multiple producer destinations, each one must have a

1631

# different monitored resource type. A metric can be used in at most

1632

# one producer destination.

1633

{ # Configuration of a specific monitoring destination (the producer project

1634

# or the consumer project).

1635

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1636

# Service.monitored_resources section.

1637

"metrics": [ # Names of the metrics to report to this monitoring destination.

1638

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

1644

# There can be multiple consumer destinations, each one must have a

1645

# different monitored resource type. A metric can be used in at most

1646

# one consumer destination.

1647

{ # Configuration of a specific monitoring destination (the producer project

1648

# or the consumer project).

1649

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1650

# Service.monitored_resources section.

1651

"metrics": [ # Names of the metrics to report to this monitoring destination.

1652

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

1659

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

1660

# by the client for tracking purpose. If empty, the server may choose to

1661

# generate one instead.

1662

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

1663

#

1664

# Example for an API targeted for external use:

1665

#

1666

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

1672

#

1673

# - selector: google.calendar.Delegate

1674

# oauth:

1675

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

1676

"rules": [ # A list of authentication rules that apply to individual API methods.

1677

#

1678

# **NOTE:** All service configuration rules follow "last one wins" order.

1679

{ # Authentication rules for the service.

1680

#

1681

# By default, if a method has any authentication requirements, every request

1682

# must include a valid credential matching one of the requirements.

1683

# It's an error to include more than one kind of credential in a single

1684

# request.

1685

#

1686

# If a method doesn't have any auth requirements, request credentials will be

1687

# ignored.

1688

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

1689

# there are scopes defined for "Read-only access to Google Calendar" and

1690

# "Access to Cloud Platform". Users can consent to a scope for an application,

1691

# giving it permission to access that data on their behalf.

1692

#

1693

# OAuth scope specifications should be fairly coarse grained; a user will need

1694

# to see and understand the text description of what your scope means.

1695

#

1696

# In most cases: use one or at most two OAuth scopes for an entire family of

1697

# products. If your product has multiple APIs, you should probably be sharing

1698

# the OAuth scope across all of those APIs.

1699

#

1700

# When you need finer grained OAuth consent screens: talk with your product

1701

# management about how developers will use them in practice.

1702

#

1703

# Please note that even though each of the canonical scopes is enough for a

1704

# request to be accepted and passed to the backend, a request can still fail

1705

# due to the backend requiring additional scopes or permissions.

1706

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

1707

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

1712

# https://www.googleapis.com/auth/calendar.read

1713

},

1714

"requirements": [ # Requirements for additional authentication providers.

1715

{ # User-defined authentication requirements, including support for

1716

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

1717

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

1722

"audiences": "A String", # The list of JWT

1723

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

1724

# that are allowed to access. A JWT containing any of these audiences will

1725

# be accepted. When this setting is absent, only JWTs with audience

1726

# "https://Service_name/API_name"

1727

# will be accepted. For example, if no audiences are in the setting,

1728

# LibraryService API will only accept JWTs with the following audience

1729

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1734

# bookstore_web.apps.googleusercontent.com

1735

},

1736

],

1737

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. If quota is enabled, an

1738

# API key is required for such request to pass the quota check.

1739

"selector": "A String", # Selects the methods to which this rule applies.

1740

#

1741

# Refer to selector for syntax details.

1742

},

1743

],

1744

"providers": [ # Defines a set of authentication providers that a service supports.

1745

{ # Configuration for an anthentication provider, including support for

1746

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

1747

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

1748

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

1749

# Optional if the key set document:

1750

# - can be retrieved from

1751

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

1752

# of the issuer.

1753

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

1754

#

1755

# Example: https://www.googleapis.com/oauth2/v1/certs

1756

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

1757

# `AuthRequirement.provider_id`.

1758

#

1759

# Example: "bookstore_auth".

1760

"issuer": "A String", # Identifies the principal that issued the JWT. See

1761

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

1762

# Usually a URL or an email address.

1763

#

1764

# Example: https://securetoken.google.com

1765

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

1770

"rules": [ # A list of usage rules that apply to individual API methods.

1771

#

1772

# **NOTE:** All service configuration rules follow "last one wins" order.

1773

{ # Usage configuration rules for the service.

1774

#

1775

# NOTE: Under development.

1776

#

1777

#

1778

# Use this rule to configure unregistered calls for the service. Unregistered

1779

# calls are calls that do not contain consumer project identity.

1780

# (Example: calls that do not contain an API key).

1781

# By default, API methods do not allow unregistered calls, and each method call

1782

# must be identified by a consumer project identity. Use this rule to

1783

# allow/disallow unregistered calls.

1784

#

1785

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1791

#

1792

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

1797

# allow_unregistered_calls: true

1798

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1799

# methods in all APIs.

1800

#

1801

# Refer to selector for syntax details.

1802

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

1803

},

1804

],

1805

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

1806

# service. Each requirement is of the form <service.name>/<requirement-id>;

1807

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

1812

# influence interpretation of the configuration, for example, to

1813

# determine defaults. This is documented together with applicable

1814

# options. The current default for the config version itself is `3`.

1815

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

1816

# Members of this project can manage the service configuration,

1817

# manage consumption of the service, etc.

1818

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

1819

# HttpRule, each specifying the mapping of an RPC method

1820

# to one or more HTTP REST API methods.

1821

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

1822

#

1823

# **NOTE:** All service configuration rules follow "last one wins" order.

1824

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

1825

# REST APIs. The mapping determines what portions of the request

1826

# message are populated from the path, query parameters, or body of

1827

# the HTTP request. The mapping is typically specified as an

1828

# `google.api.http` annotation, see "google/api/annotations.proto"

1829

# for details.

1830

#

1831

# The mapping consists of a field specifying the path template and

1832

# method kind. The path template can refer to fields in the request

1833

# message, as in the example below which describes a REST GET

1834

# operation on a resource collection of messages:

1835

#

1836

# ```proto

1837

# service Messaging {

1838

# rpc GetMessage(GetMessageRequest) returns (Message) {

1839

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

1840

# }

1841

# }

1842

# message GetMessageRequest {

1843

# message SubMessage {

1844

# string subfield = 1;

1845

# }

1846

# string message_id = 1; // mapped to the URL

1847

# SubMessage sub = 2; // `sub.subfield` is url-mapped

1848

# }

1849

# message Message {

1850

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

1855

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

1860

#

1861

# In general, not only fields but also field paths can be referenced

1862

# from a path pattern. Fields mapped to the path pattern cannot be

1863

# repeated and must have a primitive (non-message) type.

1864

#

1865

# Any fields in the request message which are not bound by the path

1866

# pattern automatically become (optional) HTTP query

1867

# parameters. Assume the following definition of the request message:

1868

#

1869

# ```proto

1870

# message GetMessageRequest {

1871

# message SubMessage {

1872

# string subfield = 1;

1873

# }

1874

# string message_id = 1; // mapped to the URL

1875

# int64 revision = 2; // becomes a parameter

1876

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

1885

#

1886

# Note that fields which are mapped to HTTP parameters must have a

1887

# primitive type or a repeated primitive type. Message types are not

1888

# allowed. In the case of a repeated type, the parameter can be

1889

# repeated in the URL, as in `...?param=A&param=B`.

1890

#

1891

# For HTTP method kinds which allow a request body, the `body` field

1892

# specifies the mapping. Consider a REST update method on the

1893

# message resource collection:

1894

#

1895

# ```proto

1896

# service Messaging {

1897

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

1898

# option (google.api.http) = {

1899

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

1905

# string message_id = 1; // mapped to the URL

1906

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

1911

# representation of the JSON in the request body is determined by

1912

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

1917

#

1918

# The special name `*` can be used in the body mapping to define that

1919

# every field not bound by the path template should be mapped to the

1920

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

1925

# rpc UpdateMessage(Message) returns (Message) {

1926

# option (google.api.http) = {

1927

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

1943

#

1944

# Note that when using `*` in the body mapping, it is not possible to

1945

# have HTTP parameters, as all fields not bound by the path end in

1946

# the body. This makes this option more rarely used in practice of

1947

# defining REST APIs. The common usage of `*` is in custom methods

1948

# which don't use the URL at all for transferring data.

1949

#

1950

# It is possible to define multiple HTTP methods for one RPC by using

1951

# the `additional_bindings` option. Example:

1952

#

1953

# ```proto

1954

# service Messaging {

1955

# rpc GetMessage(GetMessageRequest) returns (Message) {

1956

# option (google.api.http) = {

1957

# get: "/v1/messages/{message_id}"

1958

# additional_bindings {

1959

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

1965

# string message_id = 1;

1966

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

1976

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

1977

#

1978

# # Rules for HTTP mapping

1979

#

1980

# The rules for mapping HTTP path, query parameters, and body fields

1981

# to the request message are as follows:

1982

#

1983

# 1. The `body` field specifies either `*` or a field path, or is

1984

# omitted. If omitted, it assumes there is no HTTP body.

1985

# 2. Leaf fields (recursive expansion of nested messages in the

1986

# request) can be classified into three types:

1987

# (a) Matched in the URL template.

1988

# (b) Covered by body (if body is `*`, everything except (a) fields;

1989

# else everything under the body field)

1990

# (c) All other fields.

1991

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

1992

# 4. Any body sent with an HTTP request can contain only (b) fields.

1993

#

1994

# The syntax of the path template is as follows:

1995

#

1996

# Template = "/" Segments [ Verb ] ;

1997

# Segments = Segment { "/" Segment } ;

1998

# Segment = "*" | "**" | LITERAL | Variable ;

1999

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2000

# FieldPath = IDENT { "." IDENT } ;

2001

# Verb = ":" LITERAL ;

2002

#

2003

# The syntax `*` matches a single path segment. It follows the semantics of

2004

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2005

# Expansion.

2006

#

2007

# The syntax `**` matches zero or more path segments. It follows the semantics

2008

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

2009

# Expansion.

2010

#

2011

# The syntax `LITERAL` matches literal text in the URL path.

2012

#

2013

# The syntax `Variable` matches the entire path as specified by its template;

2014

# this nested template must not contain further variables. If a variable

2015

# matches a single path segment, its template may be omitted, e.g. `{var}`

2016

# is equivalent to `{var=*}`.

2017

#

2018

# NOTE: the field paths in variables and in the `body` must not refer to

2019

# repeated fields or map fields.

2020

#

2021

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2022

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2023

# a given URL path rule. The wild-card rule is useful for services that provide

2024

# content to Web (HTML) clients.

2025

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2026

# `*` for mapping all fields not captured by the path pattern to the HTTP

2027

# body. NOTE: the referred field must not be a repeated field and must be

2028

# present at the top-level of response message type.

2029

"get": "A String", # Used for listing and getting information about resources.

2030

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2031

# [][google.bytestream.RestByteStream] as an API to your

2032

# configuration.

2033

# [][google.bytestream.RestByteStream] as an API to your

2034

# configuration.

2035

"enabled": True or False, # Whether download is enabled.

2036

},

2037

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2038

# not contain an `additional_bindings` field themselves (that is,

2039

# the nesting may only be one level deep).

2040

# Object with schema name: HttpRule

2041

],

2042

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2043

# [][google.bytestream.RestByteStream] as an API to your

2044

# configuration.

2045

# [][google.bytestream.RestByteStream] as an API to your

2046

# configuration.

2047

"enabled": True or False, # Whether upload is enabled.

2048

},

2049

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2050

"path": "A String", # The path matched by this custom verb.

2051

"kind": "A String", # The name of this custom HTTP verb.

2052

},

2053

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2054

# response. Other response fields are ignored. This field is optional. When

2055

# not set, the response message will be used as HTTP body of response.

2056

# NOTE: the referred field must be not a repeated field and must be present

2057

# at the top-level of response message type.

2058

"put": "A String", # Used for updating a resource.

2059

"patch": "A String", # Used for updating a resource.

2060

"post": "A String", # Used for creating a resource.

2061

"selector": "A String", # Selects methods to which this rule applies.

2062

#

2063

# Refer to selector for syntax details.

2064

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2069

# of the google.protobuf.Api needs to be provided by the configuration

2070

# author, as the remaining fields will be derived from the IDL during the

2071

# normalization process. It is an error to specify an API interface here

2072

# which cannot be resolved against the associated IDL files.

2073

{ # Api is a light-weight descriptor for a protocol buffer service.

2074

"methods": [ # The methods of this api, in unspecified order.

2075

{ # Method represents a method of an api.

2076

"name": "A String", # The simple name of this method.

2077

"requestStreaming": True or False, # If true, the request is streamed.

2078

"responseTypeUrl": "A String", # The URL of the output message type.

2079

"requestTypeUrl": "A String", # A URL of the input message type.

2080

"responseStreaming": True or False, # If true, the response is streamed.

2081

"syntax": "A String", # The source syntax of this method.

2082

"options": [ # Any metadata attached to the method.

2083

{ # A protocol buffer option, which can be attached to a message, field,

2084

# enumeration, etc.

2085

"name": "A String", # The option's name. For example, `"java_package"`.

2086

"value": { # The option's value. For example, `"com.google.protobuf"`.

2087

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2094

# message.

2095

# protobuf element, like the file in which it is defined.

2096

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2097

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2098

},

2099

"mixins": [ # Included APIs. See Mixin.

2100

{ # Declares an API to be included in this API. The including API must

2101

# redeclare all the methods from the included API, but documentation

2102

# and options are inherited as follows:

2103

#

2104

# - If after comment and whitespace stripping, the documentation

2105

# string of the redeclared method is empty, it will be inherited

2106

# from the original method.

2107

#

2108

# - Each annotation belonging to the service config (http,

2109

# visibility) which is not set in the redeclared method will be

2110

# inherited.

2111

#

2112

# - If an http annotation is inherited, the path pattern will be

2113

# modified as follows. Any version prefix will be replaced by the

2114

# version of the including API plus the root path if specified.

2115

#

2116

# Example of a simple mixin:

2117

#

2118

# package google.acl.v1;

2119

# service AccessControl {

2120

# // Get the underlying ACL object.

2121

# rpc GetAcl(GetAclRequest) returns (Acl) {

2122

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2127

# service Storage {

2128

# // rpc GetAcl(GetAclRequest) returns (Acl);

2129

#

2130

# // Get a data record.

2131

# rpc GetData(GetDataRequest) returns (Data) {

2132

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2137

#

2138

# apis:

2139

# - name: google.storage.v2.Storage

2140

# mixins:

2141

# - name: google.acl.v1.AccessControl

2142

#

2143

# The mixin construct implies that all methods in `AccessControl` are

2144

# also declared with same name and request/response types in

2145

# `Storage`. A documentation generator or annotation processor will

2146

# see the effective `Storage.GetAcl` method after inherting

2147

# documentation and annotations as follows:

2148

#

2149

# service Storage {

2150

# // Get the underlying ACL object.

2151

# rpc GetAcl(GetAclRequest) returns (Acl) {

2152

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2158

#

2159

# If the `root` field in the mixin is specified, it should be a

2160

# relative path under which inherited HTTP paths are placed. Example:

2161

#

2162

# apis:

2163

# - name: google.storage.v2.Storage

2164

# mixins:

2165

# - name: google.acl.v1.AccessControl

2166

# root: acls

2167

#

2168

# This implies the following inherited HTTP annotation:

2169

#

2170

# service Storage {

2171

# // Get the underlying ACL object.

2172

# rpc GetAcl(GetAclRequest) returns (Acl) {

2173

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2178

# are rooted.

2179

"name": "A String", # The fully qualified name of the API which is included.

2180

},

2181

],

2182

"syntax": "A String", # The source syntax of the service.

2183

"version": "A String", # A version string for this api. If specified, must have the form

2184

# `major-version.minor-version`, as in `1.10`. If the minor version

2185

# is omitted, it defaults to zero. If the entire version field is

2186

# empty, the major version is derived from the package name, as

2187

# outlined below. If the field is not empty, the version in the

2188

# package name will be verified to be consistent with what is

2189

# provided here.

2190

#

2191

# The versioning schema uses [semantic

2192

# versioning](http://semver.org) where the major version number

2193

# indicates a breaking change and the minor version an additive,

2194

# non-breaking change. Both version numbers are signals to users

2195

# what to expect from different versions, and should be carefully

2196

# chosen based on the product plan.

2197

#

2198

# The major version is also reflected in the package name of the

2199

# API, which must end in `v<major-version>`, as in

2200

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2201

# be omitted. Zero major versions must only be used for

2202

# experimental, none-GA apis.

2203

"options": [ # Any metadata attached to the API.

2204

{ # A protocol buffer option, which can be attached to a message, field,

2205

# enumeration, etc.

2206

"name": "A String", # The option's name. For example, `"java_package"`.

2207

"value": { # The option's value. For example, `"com.google.protobuf"`.

2208

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

2213

# followed by the api's simple name.

2214

},

2215

],

2216

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2217

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2225

# - google.foo.v1.AnotherError

2226

"rules": [ # The list of custom error rules that apply to individual API messages.

2227

#

2228

# **NOTE:** All service configuration rules follow "last one wins" order.

2229

{ # A custom error rule.

2230

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2231

# objects of this type will be filtered when they appear in error payload.

2232

"selector": "A String", # Selects messages to which this rule applies.

2233

#

2234

# Refer to selector for syntax details.

2235

},

2236

],

2237

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

2242

# elements. Restrictions are specified using visibility labels

2243

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2244

#

2245

# Users and projects can have access to more than one visibility label. The

2246

# effective visibility for multiple labels is the union of each label's

2247

# elements, plus any unrestricted elements.

2248

#

2249

# If an element and its parents have no restrictions, visibility is

2250

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2257

# restriction: TRUSTED_TESTER

2258

# - selector: google.calendar.Calendar.Delegate

2259

# restriction: GOOGLE_INTERNAL

2260

#

2261

# Here, all methods are publicly visible except for the restricted methods

2262

# EnhancedSearch and Delegate.

2263

"rules": [ # A list of visibility rules that apply to individual API elements.

2264

#

2265

# **NOTE:** All service configuration rules follow "last one wins" order.

2266

{ # A visibility rule provides visibility configuration for an individual API

2267

# element.

2268

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

2269

# visibility to the element.

2270

#

2271

# If a rule has multiple labels, removing one of the labels but not all of

2272

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2279

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2280

#

2281

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2282

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2283

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2284

#

2285

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

2290

{ # Defines a metric type and its schema.

2291

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2292

# Use sentence case without an ending period, for example "Request count".

2293

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2294

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

2295

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

2296

"labels": [ # The set of labels that can be used to describe a specific instance of this

2297

# metric type. For example, the

2298

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

2299

# has a label, `loadbalanced`, that specifies whether the traffic was

2300

# received through a load balanced IP address.

2301

{ # A description of a label.

2302

"valueType": "A String", # The type of data that can be assigned to the label.

2303

"description": "A String", # A human-readable description for the label.

2304

"key": "A String", # The label key.

2305

},

2306

],

2307

"type": "A String", # The metric type including a DNS name prefix, for example

2308

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

2309

# should use a natural hierarchical grouping such as the following:

2310

#

2311

# compute.googleapis.com/instance/cpu/utilization

2312

# compute.googleapis.com/instance/disk/read_ops_count

2313

# compute.googleapis.com/instance/network/received_bytes_count

2314

#

2315

# Note that if the metric type changes, the monitoring data will be

2316

# discontinued, and anything depends on it will break, such as monitoring

2317

# dashboards, alerting rules and quota limits. Therefore, once a metric has

2318

# been published, its type should be immutable.

2319

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2320

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2321

# supported units are a subset of [The Unified Code for Units of

2322

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2323

#

2324

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

2339

# * `P` peta (10**15)

2340

# * `E` exa (10**18)

2341

# * `Z` zetta (10**21)

2342

# * `Y` yotta (10**24)

2343

# * `m` milli (10**-3)

2344

# * `u` micro (10**-6)

2345

# * `n` nano (10**-9)

2346

# * `p` pico (10**-12)

2347

# * `f` femto (10**-15)

2348

# * `a` atto (10**-18)

2349

# * `z` zepto (10**-21)

2350

# * `y` yocto (10**-24)

2351

# * `Ki` kibi (2**10)

2352

# * `Mi` mebi (2**20)

2353

# * `Gi` gibi (2**30)

2354

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2359

#

2360

# The grammar also includes these connectors:

2361

#

2362

# * `/` division (as an infix operator, e.g. `1/s`).

2363

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2364

#

2365

# The grammar for a unit is as follows:

2366

#

2367

# Expression = Component { "." Component } { "/" Component } ;

2368

#

2369

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2379

# equivalent to `1` if it is used alone. For examples,

2380

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2381

# * `NAME` is a sequence of non-blank printable ASCII characters not

2382

# containing '{' or '}'.

2383

"name": "A String", # Resource name. The format of the name may vary between different

2384

# implementations. For examples:

2385

#

2386

# projects/{project_id}/metricDescriptors/{type=**}

2387

# metricDescriptors/{type=**}

2388

},

2389

],

2390

"enums": [ # A list of all enum types included in this API service. Enums

2391

# referenced directly or indirectly by the `apis` are automatically

2392

# included. Enums which are not referenced but shall be included

2393

# should be listed here by name. Example:

2394

#

2395

# enums:

2396

# - name: google.someapi.v1.SomeEnum

2397

{ # Enum type definition.

2398

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2399

# protobuf element, like the file in which it is defined.

2400

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2401

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2402

},

2403

"enumvalue": [ # Enum value definitions.

2404

{ # Enum value definition.

2405

"number": 42, # Enum value number.

2406

"options": [ # Protocol buffer options.

2407

{ # A protocol buffer option, which can be attached to a message, field,

2408

# enumeration, etc.

2409

"name": "A String", # The option's name. For example, `"java_package"`.

2410

"value": { # The option's value. For example, `"com.google.protobuf"`.

2411

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

2416

},

2417

],

2418

"options": [ # Protocol buffer options.

2419

{ # A protocol buffer option, which can be attached to a message, field,

2420

# enumeration, etc.

2421

"name": "A String", # The option's name. For example, `"java_package"`.

2422

"value": { # The option's value. For example, `"com.google.protobuf"`.

2423

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2428

"syntax": "A String", # The source syntax.

2429

},

2430

],

2431

"types": [ # A list of all proto message types included in this API service.

2432

# Types referenced directly or indirectly by the `apis` are

2433

# automatically included. Messages which are not referenced but

2434

# shall be included, such as types used by the `google.protobuf.Any` type,

2435

# should be listed here by name. Example:

2436

#

2437

# types:

2438

# - name: google.protobuf.Int32

2439

{ # A protocol buffer message type.

2440

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2441

"A String",

2442

],

2443

"name": "A String", # The fully qualified message name.

2444

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2445

# protobuf element, like the file in which it is defined.

2446

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2447

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2448

},

2449

"syntax": "A String", # The source syntax.

2450

"fields": [ # The list of fields.

2451

{ # A single field of a message type.

2452

"kind": "A String", # The field type.

2453

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2454

# types. The first type has index 1; zero means the type is not in the list.

2455

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2456

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2457

"name": "A String", # The field name.

2458

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2459

"jsonName": "A String", # The field JSON name.

2460

"number": 42, # The field number.

2461

"cardinality": "A String", # The field cardinality.

2462

"options": [ # The protocol buffer options.

2463

{ # A protocol buffer option, which can be attached to a message, field,

2464

# enumeration, etc.

2465

"name": "A String", # The option's name. For example, `"java_package"`.

2466

"value": { # The option's value. For example, `"com.google.protobuf"`.

2467

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2472

},

2473

],

2474

"options": [ # The protocol buffer options.

2475

{ # A protocol buffer option, which can be attached to a message, field,

2476

# enumeration, etc.

2477

"name": "A String", # The option's name. For example, `"java_package"`.

2478

"value": { # The option's value. For example, `"com.google.protobuf"`.

2479

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

2486

#

2487

# The following example shows how to configure logs to be sent to the

2488

# producer and consumer projects. In the example,

2489

# the `library.googleapis.com/activity_history` log is

2490

# sent to both the producer and consumer projects, whereas

2491

# the `library.googleapis.com/purchase_history` log is only sent to the

2492

# producer project:

2493

#

2494

# monitored_resources:

2495

# - type: library.googleapis.com/branch

2496

# labels:

2497

# - key: /city

2498

# description: The city where the library branch is located in.

2499

# - key: /name

2500

# description: The name of the branch.

2501

# logs:

2502

# - name: library.googleapis.com/activity_history

2503

# labels:

2504

# - key: /customer_id

2505

# - name: library.googleapis.com/purchase_history

2506

# logging:

2507

# producer_destinations:

2508

# - monitored_resource: library.googleapis.com/branch

2509

# logs:

2510

# - library.googleapis.com/activity_history

2511

# - library.googleapis.com/purchase_history

2512

# consumer_destinations:

2513

# - monitored_resource: library.googleapis.com/branch

2514

# logs:

2515

# - library.googleapis.com/activity_history

2516

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2517

# There can be multiple producer destinations, each one must have a

2518

# different monitored resource type. A log can be used in at most

2519

# one producer destination.

2520

{ # Configuration of a specific logging destination (the producer project

2521

# or the consumer project).

2522

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2523

# Service.monitored_resources section.

2524

"logs": [ # Names of the logs to be sent to this destination. Each name must

2525

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

2531

# There can be multiple consumer destinations, each one must have a

2532

# different monitored resource type. A log can be used in at most

2533

# one consumer destination.

2534

{ # Configuration of a specific logging destination (the producer project

2535

# or the consumer project).

2536

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2537

# Service.monitored_resources section.

2538

"logs": [ # Names of the logs to be sent to this destination. Each name must

2539

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

2546

# e.g. `calendar.googleapis.com`.

2547

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2548

#

2549

# Example:

2550

# <pre><code>documentation:

2551

# summary: >

2552

# The Google Calendar API gives access

2553

# to most calendar features.

2554

# pages:

2555

# - name: Overview

2556

# content: (== include google/foo/overview.md ==)

2557

# - name: Tutorial

2558

# content: (== include google/foo/tutorial.md ==)

2559

# subpages;

2560

# - name: Java

2561

# content: (== include google/foo/tutorial_java.md ==)

2562

# rules:

2563

# - selector: google.calendar.Calendar.Get

2564

# description: >

2565

# ...

2566

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2571

# standard markdown features, definition lists, tables and fenced

2572

# code blocks are supported. Section headers can be provided and are

2573

# interpreted relative to the section nesting of the context where

2574

# a documentation fragment is embedded.

2575

#

2576

# Documentation from the IDL is merged with documentation defined

2577

# via the config at normalization time, where documentation provided

2578

# by config rules overrides IDL provided.

2579

#

2580

# A number of constructs specific to the API platform are supported

2581

# in documentation text.

2582

#

2583

# In order to reference a proto element, the following

2584

# notation can be used:

2585

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2586

# To override the display text used for the link, this can be used:

2587

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2588

# Text can be excluded from doc using the following notation:

2589

# <pre><code>(-- internal comment --)</code></pre>

2590

# Comments can be made conditional using a visibility label. The below

2591

# text will be only rendered if the `BETA` label is available:

2592

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2593

# A few directives are available in documentation. Note that

2594

# directives must appear on a single line to be properly

2595

# identified. The `include` directive includes a markdown file from

2596

# an external source:

2597

# <pre><code>(== include path/to/file ==)</code></pre>

2598

# The `resource_for` directive marks a message to be the resource of

2599

# a collection in REST view. If it is not specified, tools attempt

2600

# to infer the resource from the operations in a collection:

2601

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2602

# The directive `suppress_warning` does not directly affect documentation

2603

# and is documented together with service config validation.

2604

"rules": [ # A list of documentation rules that apply to individual API elements.

2605

#

2606

# **NOTE:** All service configuration rules follow "last one wins" order.

2607

{ # A documentation rule provides information about individual API elements.

2608

"description": "A String", # Description of the selected API(s).

2609

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2610

# element is marked as `deprecated`.

2611

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2612

# qualified name of the element which may end in "*", indicating a wildcard.

2613

# Wildcards are only allowed at the end and for a whole component of the

2614

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2615

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

2620

# <pre><code>documentation:

2621

# summary: ...

2622

# overview: (== include overview.md ==)

2623

# </code></pre>

2624

# This is a shortcut for the following declaration (using pages style):

2625

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2630

# </code></pre>

2631

# Note: you cannot specify both `overview` field and `pages` field.

2632

"summary": "A String", # A short summary of what the service does. Can only be provided by

2633

# plain text.

2634

"pages": [ # The top level pages for the documentation set.

2635

{ # Represents a documentation page. A page can contain subpages to represent

2636

# nested documentation set structure.

2637

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2638

# to include content from a Markdown file.

2639

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2640

# honored in the generated docset.

2641

# Object with schema name: Page

2642

],

2643

"name": "A String", # The name of the page. It will be used as an identity of the page to

2644

# generate URI of the page, text of the link to this page in navigation,

2645

# etc. The full page name (start from the root page name to this page

2646

# concatenated with `.`) can be used as reference to the page in your

2647

# documentation. For example:

2648

# <pre><code>pages:

2649

# - name: Tutorial

2650

# content: (== include tutorial.md ==)

2651

# subpages:

2652

# - name: Java

2653

# content: (== include tutorial_java.md ==)

2654

# </code></pre>

2655

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

2660

},

2661

"systemTypes": [ # A list of all proto message types included in this API service.

2662

# It serves similar purpose as [google.api.Service.types], except that

2663

# these types are not needed by user-defined APIs. Therefore, they will not

2664

# show up in the generated discovery doc. This field should only be used

2665

# to define system APIs in ESF.

2666

{ # A protocol buffer message type.

2667

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2668

"A String",

2669

],

2670

"name": "A String", # The fully qualified message name.

2671

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2672

# protobuf element, like the file in which it is defined.

2673

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2674

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2675

},

2676

"syntax": "A String", # The source syntax.

2677

"fields": [ # The list of fields.

2678

{ # A single field of a message type.

2679

"kind": "A String", # The field type.

2680

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2681

# types. The first type has index 1; zero means the type is not in the list.

2682

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2683

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2684

"name": "A String", # The field name.

2685

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2686

"jsonName": "A String", # The field JSON name.

2687

"number": 42, # The field number.

2688

"cardinality": "A String", # The field cardinality.

2689

"options": [ # The protocol buffer options.

2690

{ # A protocol buffer option, which can be attached to a message, field,

2691

# enumeration, etc.

2692

"name": "A String", # The option's name. For example, `"java_package"`.

2693

"value": { # The option's value. For example, `"com.google.protobuf"`.

2694

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2699

},

2700

],

2701

"options": [ # The protocol buffer options.

2702

{ # A protocol buffer option, which can be attached to a message, field,

2703

# enumeration, etc.

2704

"name": "A String", # The option's name. For example, `"java_package"`.

2705

"value": { # The option's value. For example, `"com.google.protobuf"`.

2706

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

2721

# - google.rpc.context.OriginContext

2722

#

2723

# The above specifies that all methods in the API request

2724

# `google.rpc.context.ProjectContext` and

2725

# `google.rpc.context.OriginContext`.

2726

#

2727

# Available context types are defined in package

2728

# `google.rpc.context`.

2729

"rules": [ # A list of RPC context rules that apply to individual API methods.

2730

#

2731

# **NOTE:** All service configuration rules follow "last one wins" order.

2732

{ # A context rule provides information about the context for an individual API

2733

# element.

2734

"provided": [ # A list of full type names of provided contexts.

2735

"A String",

2736

],

2737

"requested": [ # A list of full type names of requested contexts.

2738

"A String",

2739

],

2740

"selector": "A String", # Selects the methods to which this rule applies.

2741

#

2742

# Refer to selector for syntax details.

},

],

},

}</pre>

</div>

<code class="details" id="get">get(serviceName=None, configId, x__xgafv=None)</code>

2751

<pre>Gets a service configuration (version) for a managed service.

2752

2753

Args:

2754

serviceName: string, The name of the service. See the [overview](/service-management/overview)

2755

for naming requirements. For example: `example.googleapis.com`. (required)

2756

configId: string, A parameter (required)

2757

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2764

2765

{ # `Service` is the root object of the configuration schema. It

2766

# describes basic information like the name of the service and the

2767

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

2773

# config_version: 1

2774

# name: calendar.googleapis.com

2775

# title: Google Calendar API

2776

# apis:

2777

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

2782

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2783

# service controller handles features like abuse, quota, billing, logging,

2784

# monitoring, etc.

2785

"environment": "A String", # The service control environment to use. If empty, no control plane

2786

# feature (like quota and billing) will be enabled.

2787

},

2788

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

2789

# by the Service.monitoring and Service.logging configurations.

2790

{ # An object that describes the schema of a MonitoredResource object using a

2791

# type name and a set of labels. For example, the monitored resource

2792

# descriptor for Google Compute Engine VM instances has a type of

2793

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

2794

# `"zone"` to identify particular VM instances.

2795

#

2796

# Different APIs can support different monitored resource types. APIs generally

2797

# provide a `list` method that returns the monitored resource descriptors used

2798

# by the API.

2799

"type": "A String", # Required. The monitored resource type. For example, the type

2800

# `"cloudsql_database"` represents databases in Google Cloud SQL.

2801

# The maximum length of this value is 256 characters.

2802

"labels": [ # Required. A set of labels used to describe instances of this monitored

2803

# resource type. For example, an individual Google Cloud SQL database is

2804

# identified by values for the labels `"database_id"` and `"zone"`.

2805

{ # A description of a label.

2806

"valueType": "A String", # The type of data that can be assigned to the label.

2807

"description": "A String", # A human-readable description for the label.

2808

"key": "A String", # The label key.

2809

},

2810

],

2811

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

2812

# displayed in user interfaces. For example, `"Google Cloud SQL Database"`.

2813

"description": "A String", # Optional. A detailed description of the monitored resource type that might

2814

# be used in documentation.

2815

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

2816

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

2817

# {type} is the value of the `type` field in this object and

2818

# {project_id} is a project ID that provides API-specific context for

2819

# accessing the type. APIs that do not use project information can use the

2820

# resource name format `"monitoredResourceDescriptors/{type}"`.

2821

},

2822

],

2823

"logs": [ # Defines the logs used by this service.

2824

{ # A description of a log type. Example in YAML format:

2825

#

2826

# - name: library.googleapis.com/activity_history

2827

# description: The history of borrowing and returning library items.

2828

# display_name: Activity

2829

# labels:

2830

# - key: /customer_id

2831

# description: Identifier of a library customer

2832

"labels": [ # The set of labels that are available to describe a specific log entry.

2833

# Runtime requests that contain labels not specified here are

2834

# considered invalid.

2835

{ # A description of a label.

2836

"valueType": "A String", # The type of data that can be assigned to the label.

2837

"description": "A String", # A human-readable description for the label.

2838

"key": "A String", # The label key.

2839

},

2840

],

2841

"displayName": "A String", # The human-readable name for this log. This information appears on

2842

# the user interface and should be concise.

2843

"description": "A String", # A human-readable description of this log. This information appears in

2844

# the documentation and can contain details.

2845

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2846

# include the following characters: upper- and lower-case alphanumeric

2847

# characters [A-Za-z0-9], and punctuation characters including

2848

# slash, underscore, hyphen, period [/_-.].

2849

},

2850

],

2851

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

2852

#

2853

# A system parameter is a special kind of parameter defined by the API

2854

# system, not by an individual API. It is typically mapped to an HTTP header

2855

# and/or a URL query parameter. This configuration specifies which methods

2856

# change the names of the system parameters.

2857

"rules": [ # Define system parameters.

2858

#

2859

# The parameters defined here will override the default parameters

2860

# implemented by the system. If this field is missing from the service

2861

# config, default system parameters will be used. Default system parameters

2862

# and names is implementation-dependent.

2863

#

2864

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

2872

# - name: alt

2873

# http_header: Response-Content-Type

2874

#

2875

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

2880

# parameters:

2881

# - name: api_key

2882

# http_header: Api-Key1

2883

# - name: api_key

2884

# http_header: Api-Key2

2885

#

2886

# **NOTE:** All service configuration rules follow "last one wins" order.

2887

{ # Define a system parameter rule mapping system parameter definitions to

2888

# methods.

2889

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

2890

# For a given method call, only one of them should be used. If multiple

2891

# names are used the behavior is implementation-dependent.

2892

# If none of the specified names are present the behavior is

2893

# parameter-dependent.

2894

{ # Define a parameter's name and location. The parameter may be passed as either

2895

# an HTTP header or a URL query parameter, and if both are passed the behavior

2896

# is implementation-dependent.

2897

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

2898

# sensitive.

2899

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

2900

# and etc. It is case sensitive.

2901

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2906

# methods in all APIs.

2907

#

2908

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

2913

"rules": [ # A list of API backend rules that apply to individual API methods.

2914

#

2915

# **NOTE:** All service configuration rules follow "last one wins" order.

2916

{ # A backend rule provides configuration for an individual API element.

2917

"selector": "A String", # Selects the methods to which this rule applies.

2918

#

2919

# Refer to selector for syntax details.

2920

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

2921

# default depends on the deployment context.

2922

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

2927

#

2928

# The example below shows how to configure monitored resources and metrics

2929

# for monitoring. In the example, a monitored resource and two metrics are

2930

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2931

# to both producer and consumer projects, whereas the

2932

# `library.googleapis.com/book/overdue_count` metric is only sent to the

2933

# consumer project.

2934

#

2935

# monitored_resources:

2936

# - type: library.googleapis.com/branch

2937

# labels:

2938

# - key: /city

2939

# description: The city where the library branch is located in.

2940

# - key: /name

2941

# description: The name of the branch.

2942

# metrics:

2943

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2948

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2953

# monitoring:

2954

# producer_destinations:

2955

# - monitored_resource: library.googleapis.com/branch

2956

# metrics:

2957

# - library.googleapis.com/book/returned_count

2958

# consumer_destinations:

2959

# - monitored_resource: library.googleapis.com/branch

2960

# metrics:

2961

# - library.googleapis.com/book/returned_count

2962

# - library.googleapis.com/book/overdue_count

2963

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

2964

# There can be multiple producer destinations, each one must have a

2965

# different monitored resource type. A metric can be used in at most

2966

# one producer destination.

2967

{ # Configuration of a specific monitoring destination (the producer project

2968

# or the consumer project).

2969

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2970

# Service.monitored_resources section.

2971

"metrics": [ # Names of the metrics to report to this monitoring destination.

2972

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

2978

# There can be multiple consumer destinations, each one must have a

2979

# different monitored resource type. A metric can be used in at most

2980

# one consumer destination.

2981

{ # Configuration of a specific monitoring destination (the producer project

2982

# or the consumer project).

2983

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2984

# Service.monitored_resources section.

2985

"metrics": [ # Names of the metrics to report to this monitoring destination.

2986

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

2993

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

2994

# by the client for tracking purpose. If empty, the server may choose to

2995

# generate one instead.

2996

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

2997

#

2998

# Example for an API targeted for external use:

2999

#

3000

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

3006

#

3007

# - selector: google.calendar.Delegate

3008

# oauth:

3009

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

3010

"rules": [ # A list of authentication rules that apply to individual API methods.

3011

#

3012

# **NOTE:** All service configuration rules follow "last one wins" order.

3013

{ # Authentication rules for the service.

3014

#

3015

# By default, if a method has any authentication requirements, every request

3016

# must include a valid credential matching one of the requirements.

3017

# It's an error to include more than one kind of credential in a single

3018

# request.

3019

#

3020

# If a method doesn't have any auth requirements, request credentials will be

3021

# ignored.

3022

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3023

# there are scopes defined for "Read-only access to Google Calendar" and

3024

# "Access to Cloud Platform". Users can consent to a scope for an application,

3025

# giving it permission to access that data on their behalf.

3026

#

3027

# OAuth scope specifications should be fairly coarse grained; a user will need

3028

# to see and understand the text description of what your scope means.

3029

#

3030

# In most cases: use one or at most two OAuth scopes for an entire family of

3031

# products. If your product has multiple APIs, you should probably be sharing

3032

# the OAuth scope across all of those APIs.

3033

#

3034

# When you need finer grained OAuth consent screens: talk with your product

3035

# management about how developers will use them in practice.

3036

#

3037

# Please note that even though each of the canonical scopes is enough for a

3038

# request to be accepted and passed to the backend, a request can still fail

3039

# due to the backend requiring additional scopes or permissions.

3040

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3041

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3046

# https://www.googleapis.com/auth/calendar.read

3047

},

3048

"requirements": [ # Requirements for additional authentication providers.

3049

{ # User-defined authentication requirements, including support for

3050

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3051

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3056

"audiences": "A String", # The list of JWT

3057

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3058

# that are allowed to access. A JWT containing any of these audiences will

3059

# be accepted. When this setting is absent, only JWTs with audience

3060

# "https://Service_name/API_name"

3061

# will be accepted. For example, if no audiences are in the setting,

3062

# LibraryService API will only accept JWTs with the following audience

3063

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3068

# bookstore_web.apps.googleusercontent.com

3069

},

3070

],

3071

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. If quota is enabled, an

3072

# API key is required for such request to pass the quota check.

3073

"selector": "A String", # Selects the methods to which this rule applies.

3074

#

3075

# Refer to selector for syntax details.

3076

},

3077

],

3078

"providers": [ # Defines a set of authentication providers that a service supports.

3079

{ # Configuration for an anthentication provider, including support for

3080

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3081

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3082

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3083

# Optional if the key set document:

3084

# - can be retrieved from

3085

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3086

# of the issuer.

3087

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3088

#

3089

# Example: https://www.googleapis.com/oauth2/v1/certs

3090

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3091

# `AuthRequirement.provider_id`.

3092

#

3093

# Example: "bookstore_auth".

3094

"issuer": "A String", # Identifies the principal that issued the JWT. See

3095

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3096

# Usually a URL or an email address.

3097

#

3098

# Example: https://securetoken.google.com

3099

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3104

"rules": [ # A list of usage rules that apply to individual API methods.

3105

#

3106

# **NOTE:** All service configuration rules follow "last one wins" order.

3107

{ # Usage configuration rules for the service.

3108

#

3109

# NOTE: Under development.

3110

#

3111

#

3112

# Use this rule to configure unregistered calls for the service. Unregistered

3113

# calls are calls that do not contain consumer project identity.

3114

# (Example: calls that do not contain an API key).

3115

# By default, API methods do not allow unregistered calls, and each method call

3116

# must be identified by a consumer project identity. Use this rule to

3117

# allow/disallow unregistered calls.

3118

#

3119

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3125

#

3126

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3131

# allow_unregistered_calls: true

3132

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3133

# methods in all APIs.

3134

#

3135

# Refer to selector for syntax details.

3136

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3137

},

3138

],

3139

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3140

# service. Each requirement is of the form <service.name>/<requirement-id>;

3141

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3146

# influence interpretation of the configuration, for example, to

3147

# determine defaults. This is documented together with applicable

3148

# options. The current default for the config version itself is `3`.

3149

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3150

# Members of this project can manage the service configuration,

3151

# manage consumption of the service, etc.

3152

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3153

# HttpRule, each specifying the mapping of an RPC method

3154

# to one or more HTTP REST API methods.

3155

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3156

#

3157

# **NOTE:** All service configuration rules follow "last one wins" order.

3158

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3159

# REST APIs. The mapping determines what portions of the request

3160

# message are populated from the path, query parameters, or body of

3161

# the HTTP request. The mapping is typically specified as an

3162

# `google.api.http` annotation, see "google/api/annotations.proto"

3163

# for details.

3164

#

3165

# The mapping consists of a field specifying the path template and

3166

# method kind. The path template can refer to fields in the request

3167

# message, as in the example below which describes a REST GET

3168

# operation on a resource collection of messages:

3169

#

3170

# ```proto

3171

# service Messaging {

3172

# rpc GetMessage(GetMessageRequest) returns (Message) {

3173

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3174

# }

3175

# }

3176

# message GetMessageRequest {

3177

# message SubMessage {

3178

# string subfield = 1;

3179

# }

3180

# string message_id = 1; // mapped to the URL

3181

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3182

# }

3183

# message Message {

3184

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

3189

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3194

#

3195

# In general, not only fields but also field paths can be referenced

3196

# from a path pattern. Fields mapped to the path pattern cannot be

3197

# repeated and must have a primitive (non-message) type.

3198

#

3199

# Any fields in the request message which are not bound by the path

3200

# pattern automatically become (optional) HTTP query

3201

# parameters. Assume the following definition of the request message:

3202

#

3203

# ```proto

3204

# message GetMessageRequest {

3205

# message SubMessage {

3206

# string subfield = 1;

3207

# }

3208

# string message_id = 1; // mapped to the URL

3209

# int64 revision = 2; // becomes a parameter

3210

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

3219

#

3220

# Note that fields which are mapped to HTTP parameters must have a

3221

# primitive type or a repeated primitive type. Message types are not

3222

# allowed. In the case of a repeated type, the parameter can be

3223

# repeated in the URL, as in `...?param=A&param=B`.

3224

#

3225

# For HTTP method kinds which allow a request body, the `body` field

3226

# specifies the mapping. Consider a REST update method on the

3227

# message resource collection:

3228

#

3229

# ```proto

3230

# service Messaging {

3231

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3232

# option (google.api.http) = {

3233

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3239

# string message_id = 1; // mapped to the URL

3240

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

3245

# representation of the JSON in the request body is determined by

3246

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3251

#

3252

# The special name `*` can be used in the body mapping to define that

3253

# every field not bound by the path template should be mapped to the

3254

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

3259

# rpc UpdateMessage(Message) returns (Message) {

3260

# option (google.api.http) = {

3261

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

3277

#

3278

# Note that when using `*` in the body mapping, it is not possible to

3279

# have HTTP parameters, as all fields not bound by the path end in

3280

# the body. This makes this option more rarely used in practice of

3281

# defining REST APIs. The common usage of `*` is in custom methods

3282

# which don't use the URL at all for transferring data.

3283

#

3284

# It is possible to define multiple HTTP methods for one RPC by using

3285

# the `additional_bindings` option. Example:

3286

#

3287

# ```proto

3288

# service Messaging {

3289

# rpc GetMessage(GetMessageRequest) returns (Message) {

3290

# option (google.api.http) = {

3291

# get: "/v1/messages/{message_id}"

3292

# additional_bindings {

3293

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

3299

# string message_id = 1;

3300

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

3310

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

3311

#

3312

# # Rules for HTTP mapping

3313

#

3314

# The rules for mapping HTTP path, query parameters, and body fields

3315

# to the request message are as follows:

3316

#

3317

# 1. The `body` field specifies either `*` or a field path, or is

3318

# omitted. If omitted, it assumes there is no HTTP body.

3319

# 2. Leaf fields (recursive expansion of nested messages in the

3320

# request) can be classified into three types:

3321

# (a) Matched in the URL template.

3322

# (b) Covered by body (if body is `*`, everything except (a) fields;

3323

# else everything under the body field)

3324

# (c) All other fields.

3325

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

3326

# 4. Any body sent with an HTTP request can contain only (b) fields.

3327

#

3328

# The syntax of the path template is as follows:

3329

#

3330

# Template = "/" Segments [ Verb ] ;

3331

# Segments = Segment { "/" Segment } ;

3332

# Segment = "*" | "**" | LITERAL | Variable ;

3333

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3334

# FieldPath = IDENT { "." IDENT } ;

3335

# Verb = ":" LITERAL ;

3336

#

3337

# The syntax `*` matches a single path segment. It follows the semantics of

3338

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3339

# Expansion.

3340

#

3341

# The syntax `**` matches zero or more path segments. It follows the semantics

3342

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

3343

# Expansion.

3344

#

3345

# The syntax `LITERAL` matches literal text in the URL path.

3346

#

3347

# The syntax `Variable` matches the entire path as specified by its template;

3348

# this nested template must not contain further variables. If a variable

3349

# matches a single path segment, its template may be omitted, e.g. `{var}`

3350

# is equivalent to `{var=*}`.

3351

#

3352

# NOTE: the field paths in variables and in the `body` must not refer to

3353

# repeated fields or map fields.

3354

#

3355

# Use CustomHttpPattern to specify any HTTP method that is not included in the

3356

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

3357

# a given URL path rule. The wild-card rule is useful for services that provide

3358

# content to Web (HTML) clients.

3359

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

3360

# `*` for mapping all fields not captured by the path pattern to the HTTP

3361

# body. NOTE: the referred field must not be a repeated field and must be

3362

# present at the top-level of response message type.

3363

"get": "A String", # Used for listing and getting information about resources.

3364

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3365

# [][google.bytestream.RestByteStream] as an API to your

3366

# configuration.

3367

# [][google.bytestream.RestByteStream] as an API to your

3368

# configuration.

3369

"enabled": True or False, # Whether download is enabled.

3370

},

3371

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3372

# not contain an `additional_bindings` field themselves (that is,

3373

# the nesting may only be one level deep).

3374

# Object with schema name: HttpRule

3375

],

3376

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3377

# [][google.bytestream.RestByteStream] as an API to your

3378

# configuration.

3379

# [][google.bytestream.RestByteStream] as an API to your

3380

# configuration.

3381

"enabled": True or False, # Whether upload is enabled.

3382

},

3383

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

3384

"path": "A String", # The path matched by this custom verb.

3385

"kind": "A String", # The name of this custom HTTP verb.

3386

},

3387

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

3388

# response. Other response fields are ignored. This field is optional. When

3389

# not set, the response message will be used as HTTP body of response.

3390

# NOTE: the referred field must be not a repeated field and must be present

3391

# at the top-level of response message type.

3392

"put": "A String", # Used for updating a resource.

3393

"patch": "A String", # Used for updating a resource.

3394

"post": "A String", # Used for creating a resource.

3395

"selector": "A String", # Selects methods to which this rule applies.

3396

#

3397

# Refer to selector for syntax details.

3398

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3403

# of the google.protobuf.Api needs to be provided by the configuration

3404

# author, as the remaining fields will be derived from the IDL during the

3405

# normalization process. It is an error to specify an API interface here

3406

# which cannot be resolved against the associated IDL files.

3407

{ # Api is a light-weight descriptor for a protocol buffer service.

3408

"methods": [ # The methods of this api, in unspecified order.

3409

{ # Method represents a method of an api.

3410

"name": "A String", # The simple name of this method.

3411

"requestStreaming": True or False, # If true, the request is streamed.

3412

"responseTypeUrl": "A String", # The URL of the output message type.

3413

"requestTypeUrl": "A String", # A URL of the input message type.

3414

"responseStreaming": True or False, # If true, the response is streamed.

3415

"syntax": "A String", # The source syntax of this method.

3416

"options": [ # Any metadata attached to the method.

3417

{ # A protocol buffer option, which can be attached to a message, field,

3418

# enumeration, etc.

3419

"name": "A String", # The option's name. For example, `"java_package"`.

3420

"value": { # The option's value. For example, `"com.google.protobuf"`.

3421

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

3428

# message.

3429

# protobuf element, like the file in which it is defined.

3430

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3431

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3432

},

3433

"mixins": [ # Included APIs. See Mixin.

3434

{ # Declares an API to be included in this API. The including API must

3435

# redeclare all the methods from the included API, but documentation

3436

# and options are inherited as follows:

3437

#

3438

# - If after comment and whitespace stripping, the documentation

3439

# string of the redeclared method is empty, it will be inherited

3440

# from the original method.

3441

#

3442

# - Each annotation belonging to the service config (http,

3443

# visibility) which is not set in the redeclared method will be

3444

# inherited.

3445

#

3446

# - If an http annotation is inherited, the path pattern will be

3447

# modified as follows. Any version prefix will be replaced by the

3448

# version of the including API plus the root path if specified.

3449

#

3450

# Example of a simple mixin:

3451

#

3452

# package google.acl.v1;

3453

# service AccessControl {

3454

# // Get the underlying ACL object.

3455

# rpc GetAcl(GetAclRequest) returns (Acl) {

3456

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3461

# service Storage {

3462

# // rpc GetAcl(GetAclRequest) returns (Acl);

3463

#

3464

# // Get a data record.

3465

# rpc GetData(GetDataRequest) returns (Data) {

3466

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3471

#

3472

# apis:

3473

# - name: google.storage.v2.Storage

3474

# mixins:

3475

# - name: google.acl.v1.AccessControl

3476

#

3477

# The mixin construct implies that all methods in `AccessControl` are

3478

# also declared with same name and request/response types in

3479

# `Storage`. A documentation generator or annotation processor will

3480

# see the effective `Storage.GetAcl` method after inherting

3481

# documentation and annotations as follows:

3482

#

3483

# service Storage {

3484

# // Get the underlying ACL object.

3485

# rpc GetAcl(GetAclRequest) returns (Acl) {

3486

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3492

#

3493

# If the `root` field in the mixin is specified, it should be a

3494

# relative path under which inherited HTTP paths are placed. Example:

3495

#

3496

# apis:

3497

# - name: google.storage.v2.Storage

3498

# mixins:

3499

# - name: google.acl.v1.AccessControl

3500

# root: acls

3501

#

3502

# This implies the following inherited HTTP annotation:

3503

#

3504

# service Storage {

3505

# // Get the underlying ACL object.

3506

# rpc GetAcl(GetAclRequest) returns (Acl) {

3507

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3512

# are rooted.

3513

"name": "A String", # The fully qualified name of the API which is included.

3514

},

3515

],

3516

"syntax": "A String", # The source syntax of the service.

3517

"version": "A String", # A version string for this api. If specified, must have the form

3518

# `major-version.minor-version`, as in `1.10`. If the minor version

3519

# is omitted, it defaults to zero. If the entire version field is

3520

# empty, the major version is derived from the package name, as

3521

# outlined below. If the field is not empty, the version in the

3522

# package name will be verified to be consistent with what is

3523

# provided here.

3524

#

3525

# The versioning schema uses [semantic

3526

# versioning](http://semver.org) where the major version number

3527

# indicates a breaking change and the minor version an additive,

3528

# non-breaking change. Both version numbers are signals to users

3529

# what to expect from different versions, and should be carefully

3530

# chosen based on the product plan.

3531

#

3532

# The major version is also reflected in the package name of the

3533

# API, which must end in `v<major-version>`, as in

3534

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3535

# be omitted. Zero major versions must only be used for

3536

# experimental, none-GA apis.

3537

"options": [ # Any metadata attached to the API.

3538

{ # A protocol buffer option, which can be attached to a message, field,

3539

# enumeration, etc.

3540

"name": "A String", # The option's name. For example, `"java_package"`.

3541

"value": { # The option's value. For example, `"com.google.protobuf"`.

3542

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

3547

# followed by the api's simple name.

3548

},

3549

],

3550

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3551

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3559

# - google.foo.v1.AnotherError

3560

"rules": [ # The list of custom error rules that apply to individual API messages.

3561

#

3562

# **NOTE:** All service configuration rules follow "last one wins" order.

3563

{ # A custom error rule.

3564

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3565

# objects of this type will be filtered when they appear in error payload.

3566

"selector": "A String", # Selects messages to which this rule applies.

3567

#

3568

# Refer to selector for syntax details.

3569

},

3570

],

3571

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

3576

# elements. Restrictions are specified using visibility labels

3577

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3578

#

3579

# Users and projects can have access to more than one visibility label. The

3580

# effective visibility for multiple labels is the union of each label's

3581

# elements, plus any unrestricted elements.

3582

#

3583

# If an element and its parents have no restrictions, visibility is

3584

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3591

# restriction: TRUSTED_TESTER

3592

# - selector: google.calendar.Calendar.Delegate

3593

# restriction: GOOGLE_INTERNAL

3594

#

3595

# Here, all methods are publicly visible except for the restricted methods

3596

# EnhancedSearch and Delegate.

3597

"rules": [ # A list of visibility rules that apply to individual API elements.

3598

#

3599

# **NOTE:** All service configuration rules follow "last one wins" order.

3600

{ # A visibility rule provides visibility configuration for an individual API

3601

# element.

3602

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

3603

# visibility to the element.

3604

#

3605

# If a rule has multiple labels, removing one of the labels but not all of

3606

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3613

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

3614

#

3615

# Removing GOOGLE_INTERNAL from this restriction will break clients that

3616

# rely on this method and only had access to it through GOOGLE_INTERNAL.

3617

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

3618

#

3619

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

3624

{ # Defines a metric type and its schema.

3625

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3626

# Use sentence case without an ending period, for example "Request count".

3627

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3628

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

3629

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

3630

"labels": [ # The set of labels that can be used to describe a specific instance of this

3631

# metric type. For example, the

3632

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

3633

# has a label, `loadbalanced`, that specifies whether the traffic was

3634

# received through a load balanced IP address.

3635

{ # A description of a label.

3636

"valueType": "A String", # The type of data that can be assigned to the label.

3637

"description": "A String", # A human-readable description for the label.

3638

"key": "A String", # The label key.

3639

},

3640

],

3641

"type": "A String", # The metric type including a DNS name prefix, for example

3642

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

3643

# should use a natural hierarchical grouping such as the following:

3644

#

3645

# compute.googleapis.com/instance/cpu/utilization

3646

# compute.googleapis.com/instance/disk/read_ops_count

3647

# compute.googleapis.com/instance/network/received_bytes_count

3648

#

3649

# Note that if the metric type changes, the monitoring data will be

3650

# discontinued, and anything depends on it will break, such as monitoring

3651

# dashboards, alerting rules and quota limits. Therefore, once a metric has

3652

# been published, its type should be immutable.

3653

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

3654

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

3655

# supported units are a subset of [The Unified Code for Units of

3656

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3657

#

3658

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

3673

# * `P` peta (10**15)

3674

# * `E` exa (10**18)

3675

# * `Z` zetta (10**21)

3676

# * `Y` yotta (10**24)

3677

# * `m` milli (10**-3)

3678

# * `u` micro (10**-6)

3679

# * `n` nano (10**-9)

3680

# * `p` pico (10**-12)

3681

# * `f` femto (10**-15)

3682

# * `a` atto (10**-18)

3683

# * `z` zepto (10**-21)

3684

# * `y` yocto (10**-24)

3685

# * `Ki` kibi (2**10)

3686

# * `Mi` mebi (2**20)

3687

# * `Gi` gibi (2**30)

3688

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

3693

#

3694

# The grammar also includes these connectors:

3695

#

3696

# * `/` division (as an infix operator, e.g. `1/s`).

3697

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

3698

#

3699

# The grammar for a unit is as follows:

3700

#

3701

# Expression = Component { "." Component } { "/" Component } ;

3702

#

3703

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

3713

# equivalent to `1` if it is used alone. For examples,

3714

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

3715

# * `NAME` is a sequence of non-blank printable ASCII characters not

3716

# containing '{' or '}'.

3717

"name": "A String", # Resource name. The format of the name may vary between different

3718

# implementations. For examples:

3719

#

3720

# projects/{project_id}/metricDescriptors/{type=**}

3721

# metricDescriptors/{type=**}

3722

},

3723

],

3724

"enums": [ # A list of all enum types included in this API service. Enums

3725

# referenced directly or indirectly by the `apis` are automatically

3726

# included. Enums which are not referenced but shall be included

3727

# should be listed here by name. Example:

3728

#

3729

# enums:

3730

# - name: google.someapi.v1.SomeEnum

3731

{ # Enum type definition.

3732

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3733

# protobuf element, like the file in which it is defined.

3734

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3735

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3736

},

3737

"enumvalue": [ # Enum value definitions.

3738

{ # Enum value definition.

3739

"number": 42, # Enum value number.

3740

"options": [ # Protocol buffer options.

3741

{ # A protocol buffer option, which can be attached to a message, field,

3742

# enumeration, etc.

3743

"name": "A String", # The option's name. For example, `"java_package"`.

3744

"value": { # The option's value. For example, `"com.google.protobuf"`.

3745

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

3750

},

3751

],

3752

"options": [ # Protocol buffer options.

3753

{ # A protocol buffer option, which can be attached to a message, field,

3754

# enumeration, etc.

3755

"name": "A String", # The option's name. For example, `"java_package"`.

3756

"value": { # The option's value. For example, `"com.google.protobuf"`.

3757

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

3762

"syntax": "A String", # The source syntax.

3763

},

3764

],

3765

"types": [ # A list of all proto message types included in this API service.

3766

# Types referenced directly or indirectly by the `apis` are

3767

# automatically included. Messages which are not referenced but

3768

# shall be included, such as types used by the `google.protobuf.Any` type,

3769

# should be listed here by name. Example:

3770

#

3771

# types:

3772

# - name: google.protobuf.Int32

3773

{ # A protocol buffer message type.

3774

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3775

"A String",

3776

],

3777

"name": "A String", # The fully qualified message name.

3778

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3779

# protobuf element, like the file in which it is defined.

3780

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3781

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3782

},

3783

"syntax": "A String", # The source syntax.

3784

"fields": [ # The list of fields.

3785

{ # A single field of a message type.

3786

"kind": "A String", # The field type.

3787

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3788

# types. The first type has index 1; zero means the type is not in the list.

3789

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3790

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3791

"name": "A String", # The field name.

3792

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3793

"jsonName": "A String", # The field JSON name.

3794

"number": 42, # The field number.

3795

"cardinality": "A String", # The field cardinality.

3796

"options": [ # The protocol buffer options.

3797

{ # A protocol buffer option, which can be attached to a message, field,

3798

# enumeration, etc.

3799

"name": "A String", # The option's name. For example, `"java_package"`.

3800

"value": { # The option's value. For example, `"com.google.protobuf"`.

3801

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3806

},

3807

],

3808

"options": [ # The protocol buffer options.

3809

{ # A protocol buffer option, which can be attached to a message, field,

3810

# enumeration, etc.

3811

"name": "A String", # The option's name. For example, `"java_package"`.

3812

"value": { # The option's value. For example, `"com.google.protobuf"`.

3813

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

3820

#

3821

# The following example shows how to configure logs to be sent to the

3822

# producer and consumer projects. In the example,

3823

# the `library.googleapis.com/activity_history` log is

3824

# sent to both the producer and consumer projects, whereas

3825

# the `library.googleapis.com/purchase_history` log is only sent to the

3826

# producer project:

3827

#

3828

# monitored_resources:

3829

# - type: library.googleapis.com/branch

3830

# labels:

3831

# - key: /city

3832

# description: The city where the library branch is located in.

3833

# - key: /name

3834

# description: The name of the branch.

3835

# logs:

3836

# - name: library.googleapis.com/activity_history

3837

# labels:

3838

# - key: /customer_id

3839

# - name: library.googleapis.com/purchase_history

3840

# logging:

3841

# producer_destinations:

3842

# - monitored_resource: library.googleapis.com/branch

3843

# logs:

3844

# - library.googleapis.com/activity_history

3845

# - library.googleapis.com/purchase_history

3846

# consumer_destinations:

3847

# - monitored_resource: library.googleapis.com/branch

3848

# logs:

3849

# - library.googleapis.com/activity_history

3850

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3851

# There can be multiple producer destinations, each one must have a

3852

# different monitored resource type. A log can be used in at most

3853

# one producer destination.

3854

{ # Configuration of a specific logging destination (the producer project

3855

# or the consumer project).

3856

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3857

# Service.monitored_resources section.

3858

"logs": [ # Names of the logs to be sent to this destination. Each name must

3859

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

3865

# There can be multiple consumer destinations, each one must have a

3866

# different monitored resource type. A log can be used in at most

3867

# one consumer destination.

3868

{ # Configuration of a specific logging destination (the producer project

3869

# or the consumer project).

3870

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3871

# Service.monitored_resources section.

3872

"logs": [ # Names of the logs to be sent to this destination. Each name must

3873

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

3880

# e.g. `calendar.googleapis.com`.

3881

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

3882

#

3883

# Example:

3884

# <pre><code>documentation:

3885

# summary: >

3886

# The Google Calendar API gives access

3887

# to most calendar features.

3888

# pages:

3889

# - name: Overview

3890

# content: (== include google/foo/overview.md ==)

3891

# - name: Tutorial

3892

# content: (== include google/foo/tutorial.md ==)

3893

# subpages;

3894

# - name: Java

3895

# content: (== include google/foo/tutorial_java.md ==)

3896

# rules:

3897

# - selector: google.calendar.Calendar.Get

3898

# description: >

3899

# ...

3900

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3905

# standard markdown features, definition lists, tables and fenced

3906

# code blocks are supported. Section headers can be provided and are

3907

# interpreted relative to the section nesting of the context where

3908

# a documentation fragment is embedded.

3909

#

3910

# Documentation from the IDL is merged with documentation defined

3911

# via the config at normalization time, where documentation provided

3912

# by config rules overrides IDL provided.

3913

#

3914

# A number of constructs specific to the API platform are supported

3915

# in documentation text.

3916

#

3917

# In order to reference a proto element, the following

3918

# notation can be used:

3919

# <pre><code>[fully.qualified.proto.name][]</code></pre>

3920

# To override the display text used for the link, this can be used:

3921

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

3922

# Text can be excluded from doc using the following notation:

3923

# <pre><code>(-- internal comment --)</code></pre>

3924

# Comments can be made conditional using a visibility label. The below

3925

# text will be only rendered if the `BETA` label is available:

3926

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

3927

# A few directives are available in documentation. Note that

3928

# directives must appear on a single line to be properly

3929

# identified. The `include` directive includes a markdown file from

3930

# an external source:

3931

# <pre><code>(== include path/to/file ==)</code></pre>

3932

# The `resource_for` directive marks a message to be the resource of

3933

# a collection in REST view. If it is not specified, tools attempt

3934

# to infer the resource from the operations in a collection:

3935

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

3936

# The directive `suppress_warning` does not directly affect documentation

3937

# and is documented together with service config validation.

3938

"rules": [ # A list of documentation rules that apply to individual API elements.

3939

#

3940

# **NOTE:** All service configuration rules follow "last one wins" order.

3941

{ # A documentation rule provides information about individual API elements.

3942

"description": "A String", # Description of the selected API(s).

3943

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

3944

# element is marked as `deprecated`.

3945

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3946

# qualified name of the element which may end in "*", indicating a wildcard.

3947

# Wildcards are only allowed at the end and for a whole component of the

3948

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

3949

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

3954

# <pre><code>documentation:

3955

# summary: ...

3956

# overview: (== include overview.md ==)

3957

# </code></pre>

3958

# This is a shortcut for the following declaration (using pages style):

3959

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

3964

# </code></pre>

3965

# Note: you cannot specify both `overview` field and `pages` field.

3966

"summary": "A String", # A short summary of what the service does. Can only be provided by

3967

# plain text.

3968

"pages": [ # The top level pages for the documentation set.

3969

{ # Represents a documentation page. A page can contain subpages to represent

3970

# nested documentation set structure.

3971

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

3972

# to include content from a Markdown file.

3973

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3974

# honored in the generated docset.

3975

# Object with schema name: Page

3976

],

3977

"name": "A String", # The name of the page. It will be used as an identity of the page to

3978

# generate URI of the page, text of the link to this page in navigation,

3979

# etc. The full page name (start from the root page name to this page

3980

# concatenated with `.`) can be used as reference to the page in your

3981

# documentation. For example:

3982

# <pre><code>pages:

3983

# - name: Tutorial

3984

# content: (== include tutorial.md ==)

3985

# subpages:

3986

# - name: Java

3987

# content: (== include tutorial_java.md ==)

3988

# </code></pre>

3989

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

3994

},

3995

"systemTypes": [ # A list of all proto message types included in this API service.

3996

# It serves similar purpose as [google.api.Service.types], except that

3997

# these types are not needed by user-defined APIs. Therefore, they will not

3998

# show up in the generated discovery doc. This field should only be used

3999

# to define system APIs in ESF.

4000

{ # A protocol buffer message type.

4001

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4002

"A String",

4003

],

4004

"name": "A String", # The fully qualified message name.

4005

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4006

# protobuf element, like the file in which it is defined.

4007

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4008

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4009

},

4010

"syntax": "A String", # The source syntax.

4011

"fields": [ # The list of fields.

4012

{ # A single field of a message type.

4013

"kind": "A String", # The field type.

4014

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4015

# types. The first type has index 1; zero means the type is not in the list.

4016

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4017

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4018

"name": "A String", # The field name.

4019

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4020

"jsonName": "A String", # The field JSON name.

4021

"number": 42, # The field number.

4022

"cardinality": "A String", # The field cardinality.

4023

"options": [ # The protocol buffer options.

4024

{ # A protocol buffer option, which can be attached to a message, field,

4025

# enumeration, etc.

4026

"name": "A String", # The option's name. For example, `"java_package"`.

4027

"value": { # The option's value. For example, `"com.google.protobuf"`.

4028

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4033

},

4034

],

4035

"options": [ # The protocol buffer options.

4036

{ # A protocol buffer option, which can be attached to a message, field,

4037

# enumeration, etc.

4038

"name": "A String", # The option's name. For example, `"java_package"`.

4039

"value": { # The option's value. For example, `"com.google.protobuf"`.

4040

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

4055

# - google.rpc.context.OriginContext

4056

#

4057

# The above specifies that all methods in the API request

4058

# `google.rpc.context.ProjectContext` and

4059

# `google.rpc.context.OriginContext`.

4060

#

4061

# Available context types are defined in package

4062

# `google.rpc.context`.

4063

"rules": [ # A list of RPC context rules that apply to individual API methods.

4064

#

4065

# **NOTE:** All service configuration rules follow "last one wins" order.

4066

{ # A context rule provides information about the context for an individual API

4067

# element.

4068

"provided": [ # A list of full type names of provided contexts.

4069

"A String",

4070

],

4071

"requested": [ # A list of full type names of requested contexts.

4072

"A String",

4073

],

4074

"selector": "A String", # Selects the methods to which this rule applies.

4075

#

4076

# Refer to selector for syntax details.

},

],

},

}</pre>

</div>

<code class="details" id="list">list(serviceName=None, pageSize=None, pageToken=None, x__xgafv=None)</code>

4085

<pre>Lists the history of the service configuration for a managed service,

4086

from the newest to the oldest.

4087

4088

Args:

4089

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4090

for naming requirements. For example: `example.googleapis.com`. (required)

4091

pageSize: integer, The max number of items to include in the response list.

4092

pageToken: string, The token of the page to retrieve.

4093

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4100

4101

{ # Response message for ListServiceConfigs method.

4102

"nextPageToken": "A String", # The token of the next page of results.

4103

"serviceConfigs": [ # The list of service configuration resources.

4104

{ # `Service` is the root object of the configuration schema. It

4105

# describes basic information like the name of the service and the

4106

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

4112

# config_version: 1

4113

# name: calendar.googleapis.com

4114

# title: Google Calendar API

4115

# apis:

4116

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

4121

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4122

# service controller handles features like abuse, quota, billing, logging,

4123

# monitoring, etc.

4124

"environment": "A String", # The service control environment to use. If empty, no control plane

4125

# feature (like quota and billing) will be enabled.

4126

},

4127

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4128

# by the Service.monitoring and Service.logging configurations.

4129

{ # An object that describes the schema of a MonitoredResource object using a

4130

# type name and a set of labels. For example, the monitored resource

4131

# descriptor for Google Compute Engine VM instances has a type of

4132

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4133

# `"zone"` to identify particular VM instances.

4134

#

4135

# Different APIs can support different monitored resource types. APIs generally

4136

# provide a `list` method that returns the monitored resource descriptors used

4137

# by the API.

4138

"type": "A String", # Required. The monitored resource type. For example, the type

4139

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4140

# The maximum length of this value is 256 characters.

4141

"labels": [ # Required. A set of labels used to describe instances of this monitored

4142

# resource type. For example, an individual Google Cloud SQL database is

4143

# identified by values for the labels `"database_id"` and `"zone"`.

4144

{ # A description of a label.

4145

"valueType": "A String", # The type of data that can be assigned to the label.

4146

"description": "A String", # A human-readable description for the label.

4147

"key": "A String", # The label key.

4148

},

4149

],

4150

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

4151

# displayed in user interfaces. For example, `"Google Cloud SQL Database"`.

4152

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4153

# be used in documentation.

4154

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4155

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4156

# {type} is the value of the `type` field in this object and

4157

# {project_id} is a project ID that provides API-specific context for

4158

# accessing the type. APIs that do not use project information can use the

4159

# resource name format `"monitoredResourceDescriptors/{type}"`.

4160

},

4161

],

4162

"logs": [ # Defines the logs used by this service.

4163

{ # A description of a log type. Example in YAML format:

4164

#

4165

# - name: library.googleapis.com/activity_history

4166

# description: The history of borrowing and returning library items.

4167

# display_name: Activity

4168

# labels:

4169

# - key: /customer_id

4170

# description: Identifier of a library customer

4171

"labels": [ # The set of labels that are available to describe a specific log entry.

4172

# Runtime requests that contain labels not specified here are

4173

# considered invalid.

4174

{ # A description of a label.

4175

"valueType": "A String", # The type of data that can be assigned to the label.

4176

"description": "A String", # A human-readable description for the label.

4177

"key": "A String", # The label key.

4178

},

4179

],

4180

"displayName": "A String", # The human-readable name for this log. This information appears on

4181

# the user interface and should be concise.

4182

"description": "A String", # A human-readable description of this log. This information appears in

4183

# the documentation and can contain details.

4184

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4185

# include the following characters: upper- and lower-case alphanumeric

4186

# characters [A-Za-z0-9], and punctuation characters including

4187

# slash, underscore, hyphen, period [/_-.].

4188

},

4189

],

4190

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

4191

#

4192

# A system parameter is a special kind of parameter defined by the API

4193

# system, not by an individual API. It is typically mapped to an HTTP header

4194

# and/or a URL query parameter. This configuration specifies which methods

4195

# change the names of the system parameters.

4196

"rules": [ # Define system parameters.

4197

#

4198

# The parameters defined here will override the default parameters

4199

# implemented by the system. If this field is missing from the service

4200

# config, default system parameters will be used. Default system parameters

4201

# and names is implementation-dependent.

4202

#

4203

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4211

# - name: alt

4212

# http_header: Response-Content-Type

4213

#

4214

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4219

# parameters:

4220

# - name: api_key

4221

# http_header: Api-Key1

4222

# - name: api_key

4223

# http_header: Api-Key2

4224

#

4225

# **NOTE:** All service configuration rules follow "last one wins" order.

4226

{ # Define a system parameter rule mapping system parameter definitions to

4227

# methods.

4228

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4229

# For a given method call, only one of them should be used. If multiple

4230

# names are used the behavior is implementation-dependent.

4231

# If none of the specified names are present the behavior is

4232

# parameter-dependent.

4233

{ # Define a parameter's name and location. The parameter may be passed as either

4234

# an HTTP header or a URL query parameter, and if both are passed the behavior

4235

# is implementation-dependent.

4236

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4237

# sensitive.

4238

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

4239

# and etc. It is case sensitive.

4240

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4245

# methods in all APIs.

4246

#

4247

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4252

"rules": [ # A list of API backend rules that apply to individual API methods.

4253

#

4254

# **NOTE:** All service configuration rules follow "last one wins" order.

4255

{ # A backend rule provides configuration for an individual API element.

4256

"selector": "A String", # Selects the methods to which this rule applies.

4257

#

4258

# Refer to selector for syntax details.

4259

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4260

# default depends on the deployment context.

4261

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

4266

#

4267

# The example below shows how to configure monitored resources and metrics

4268

# for monitoring. In the example, a monitored resource and two metrics are

4269

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4270

# to both producer and consumer projects, whereas the

4271

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4272

# consumer project.

4273

#

4274

# monitored_resources:

4275

# - type: library.googleapis.com/branch

4276

# labels:

4277

# - key: /city

4278

# description: The city where the library branch is located in.

4279

# - key: /name

4280

# description: The name of the branch.

4281

# metrics:

4282

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4287

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4292

# monitoring:

4293

# producer_destinations:

4294

# - monitored_resource: library.googleapis.com/branch

4295

# metrics:

4296

# - library.googleapis.com/book/returned_count

4297

# consumer_destinations:

4298

# - monitored_resource: library.googleapis.com/branch

4299

# metrics:

4300

# - library.googleapis.com/book/returned_count

4301

# - library.googleapis.com/book/overdue_count

4302

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4303

# There can be multiple producer destinations, each one must have a

4304

# different monitored resource type. A metric can be used in at most

4305

# one producer destination.

4306

{ # Configuration of a specific monitoring destination (the producer project

4307

# or the consumer project).

4308

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4309

# Service.monitored_resources section.

4310

"metrics": [ # Names of the metrics to report to this monitoring destination.

4311

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4317

# There can be multiple consumer destinations, each one must have a

4318

# different monitored resource type. A metric can be used in at most

4319

# one consumer destination.

4320

{ # Configuration of a specific monitoring destination (the producer project

4321

# or the consumer project).

4322

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4323

# Service.monitored_resources section.

4324

"metrics": [ # Names of the metrics to report to this monitoring destination.

4325

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

4332

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4333

# by the client for tracking purpose. If empty, the server may choose to

4334

# generate one instead.

4335

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4336

#

4337

# Example for an API targeted for external use:

4338

#

4339

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

4345

#

4346

# - selector: google.calendar.Delegate

4347

# oauth:

4348

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

4349

"rules": [ # A list of authentication rules that apply to individual API methods.

4350

#

4351

# **NOTE:** All service configuration rules follow "last one wins" order.

4352

{ # Authentication rules for the service.

4353

#

4354

# By default, if a method has any authentication requirements, every request

4355

# must include a valid credential matching one of the requirements.

4356

# It's an error to include more than one kind of credential in a single

4357

# request.

4358

#

4359

# If a method doesn't have any auth requirements, request credentials will be

4360

# ignored.

4361

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4362

# there are scopes defined for "Read-only access to Google Calendar" and

4363

# "Access to Cloud Platform". Users can consent to a scope for an application,

4364

# giving it permission to access that data on their behalf.

4365

#

4366

# OAuth scope specifications should be fairly coarse grained; a user will need

4367

# to see and understand the text description of what your scope means.

4368

#

4369

# In most cases: use one or at most two OAuth scopes for an entire family of

4370

# products. If your product has multiple APIs, you should probably be sharing

4371

# the OAuth scope across all of those APIs.

4372

#

4373

# When you need finer grained OAuth consent screens: talk with your product

4374

# management about how developers will use them in practice.

4375

#

4376

# Please note that even though each of the canonical scopes is enough for a

4377

# request to be accepted and passed to the backend, a request can still fail

4378

# due to the backend requiring additional scopes or permissions.

4379

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4380

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4385

# https://www.googleapis.com/auth/calendar.read

4386

},

4387

"requirements": [ # Requirements for additional authentication providers.

4388

{ # User-defined authentication requirements, including support for

4389

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4390

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

4395

"audiences": "A String", # The list of JWT

4396

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4397

# that are allowed to access. A JWT containing any of these audiences will

4398

# be accepted. When this setting is absent, only JWTs with audience

4399

# "https://Service_name/API_name"

4400

# will be accepted. For example, if no audiences are in the setting,

4401

# LibraryService API will only accept JWTs with the following audience

4402

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4407

# bookstore_web.apps.googleusercontent.com

4408

},

4409

],

4410

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. If quota is enabled, an

4411

# API key is required for such request to pass the quota check.

4412

"selector": "A String", # Selects the methods to which this rule applies.

4413

#

4414

# Refer to selector for syntax details.

4415

},

4416

],

4417

"providers": [ # Defines a set of authentication providers that a service supports.

4418

{ # Configuration for an anthentication provider, including support for

4419

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4420

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4421

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4422

# Optional if the key set document:

4423

# - can be retrieved from

4424

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4425

# of the issuer.

4426

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4427

#

4428

# Example: https://www.googleapis.com/oauth2/v1/certs

4429

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4430

# `AuthRequirement.provider_id`.

4431

#

4432

# Example: "bookstore_auth".

4433

"issuer": "A String", # Identifies the principal that issued the JWT. See

4434

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4435

# Usually a URL or an email address.

4436

#

4437

# Example: https://securetoken.google.com

4438

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4443

"rules": [ # A list of usage rules that apply to individual API methods.

4444

#

4445

# **NOTE:** All service configuration rules follow "last one wins" order.

4446

{ # Usage configuration rules for the service.

4447

#

4448

# NOTE: Under development.

4449

#

4450

#

4451

# Use this rule to configure unregistered calls for the service. Unregistered

4452

# calls are calls that do not contain consumer project identity.

4453

# (Example: calls that do not contain an API key).

4454

# By default, API methods do not allow unregistered calls, and each method call

4455

# must be identified by a consumer project identity. Use this rule to

4456

# allow/disallow unregistered calls.

4457

#

4458

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4464

#

4465

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4470

# allow_unregistered_calls: true

4471

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4472

# methods in all APIs.

4473

#

4474

# Refer to selector for syntax details.

4475

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4476

},

4477

],

4478

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4479

# service. Each requirement is of the form <service.name>/<requirement-id>;

4480

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

4485

# influence interpretation of the configuration, for example, to

4486

# determine defaults. This is documented together with applicable

4487

# options. The current default for the config version itself is `3`.

4488

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

4489

# Members of this project can manage the service configuration,

4490

# manage consumption of the service, etc.

4491

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

4492

# HttpRule, each specifying the mapping of an RPC method

4493

# to one or more HTTP REST API methods.

4494

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4495

#

4496

# **NOTE:** All service configuration rules follow "last one wins" order.

4497

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

4498

# REST APIs. The mapping determines what portions of the request

4499

# message are populated from the path, query parameters, or body of

4500

# the HTTP request. The mapping is typically specified as an

4501

# `google.api.http` annotation, see "google/api/annotations.proto"

4502

# for details.

4503

#

4504

# The mapping consists of a field specifying the path template and

4505

# method kind. The path template can refer to fields in the request

4506

# message, as in the example below which describes a REST GET

4507

# operation on a resource collection of messages:

4508

#

4509

# ```proto

4510

# service Messaging {

4511

# rpc GetMessage(GetMessageRequest) returns (Message) {

4512

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4513

# }

4514

# }

4515

# message GetMessageRequest {

4516

# message SubMessage {

4517

# string subfield = 1;

4518

# }

4519

# string message_id = 1; // mapped to the URL

4520

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4521

# }

4522

# message Message {

4523

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

4528

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4533

#

4534

# In general, not only fields but also field paths can be referenced

4535

# from a path pattern. Fields mapped to the path pattern cannot be

4536

# repeated and must have a primitive (non-message) type.

4537

#

4538

# Any fields in the request message which are not bound by the path

4539

# pattern automatically become (optional) HTTP query

4540

# parameters. Assume the following definition of the request message:

4541

#

4542

# ```proto

4543

# message GetMessageRequest {

4544

# message SubMessage {

4545

# string subfield = 1;

4546

# }

4547

# string message_id = 1; // mapped to the URL

4548

# int64 revision = 2; // becomes a parameter

4549

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

4558

#

4559

# Note that fields which are mapped to HTTP parameters must have a

4560

# primitive type or a repeated primitive type. Message types are not

4561

# allowed. In the case of a repeated type, the parameter can be

4562

# repeated in the URL, as in `...?param=A&param=B`.

4563

#

4564

# For HTTP method kinds which allow a request body, the `body` field

4565

# specifies the mapping. Consider a REST update method on the

4566

# message resource collection:

4567

#

4568

# ```proto

4569

# service Messaging {

4570

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4571

# option (google.api.http) = {

4572

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4578

# string message_id = 1; // mapped to the URL

4579

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

4584

# representation of the JSON in the request body is determined by

4585

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

4590

#

4591

# The special name `*` can be used in the body mapping to define that

4592

# every field not bound by the path template should be mapped to the

4593

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

4598

# rpc UpdateMessage(Message) returns (Message) {

4599

# option (google.api.http) = {

4600

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

4616

#

4617

# Note that when using `*` in the body mapping, it is not possible to

4618

# have HTTP parameters, as all fields not bound by the path end in

4619

# the body. This makes this option more rarely used in practice of

4620

# defining REST APIs. The common usage of `*` is in custom methods

4621

# which don't use the URL at all for transferring data.

4622

#

4623

# It is possible to define multiple HTTP methods for one RPC by using

4624

# the `additional_bindings` option. Example:

4625

#

4626

# ```proto

4627

# service Messaging {

4628

# rpc GetMessage(GetMessageRequest) returns (Message) {

4629

# option (google.api.http) = {

4630

# get: "/v1/messages/{message_id}"

4631

# additional_bindings {

4632

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

4638

# string message_id = 1;

4639

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4649

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

4650

#

4651

# # Rules for HTTP mapping

4652

#

4653

# The rules for mapping HTTP path, query parameters, and body fields

4654

# to the request message are as follows:

4655

#

4656

# 1. The `body` field specifies either `*` or a field path, or is

4657

# omitted. If omitted, it assumes there is no HTTP body.

4658

# 2. Leaf fields (recursive expansion of nested messages in the

4659

# request) can be classified into three types:

4660

# (a) Matched in the URL template.

4661

# (b) Covered by body (if body is `*`, everything except (a) fields;

4662

# else everything under the body field)

4663

# (c) All other fields.

4664

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

4665

# 4. Any body sent with an HTTP request can contain only (b) fields.

4666

#

4667

# The syntax of the path template is as follows:

4668

#

4669

# Template = "/" Segments [ Verb ] ;

4670

# Segments = Segment { "/" Segment } ;

4671

# Segment = "*" | "**" | LITERAL | Variable ;

4672

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4673

# FieldPath = IDENT { "." IDENT } ;

4674

# Verb = ":" LITERAL ;

4675

#

4676

# The syntax `*` matches a single path segment. It follows the semantics of

4677

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4678

# Expansion.

4679

#

4680

# The syntax `**` matches zero or more path segments. It follows the semantics

4681

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

4682

# Expansion.

4683

#

4684

# The syntax `LITERAL` matches literal text in the URL path.

4685

#

4686

# The syntax `Variable` matches the entire path as specified by its template;

4687

# this nested template must not contain further variables. If a variable

4688

# matches a single path segment, its template may be omitted, e.g. `{var}`

4689

# is equivalent to `{var=*}`.

4690

#

4691

# NOTE: the field paths in variables and in the `body` must not refer to

4692

# repeated fields or map fields.

4693

#

4694

# Use CustomHttpPattern to specify any HTTP method that is not included in the

4695

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

4696

# a given URL path rule. The wild-card rule is useful for services that provide

4697

# content to Web (HTML) clients.

4698

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

4699

# `*` for mapping all fields not captured by the path pattern to the HTTP

4700

# body. NOTE: the referred field must not be a repeated field and must be

4701

# present at the top-level of response message type.

4702

"get": "A String", # Used for listing and getting information about resources.

4703

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4704

# [][google.bytestream.RestByteStream] as an API to your

4705

# configuration.

4706

# [][google.bytestream.RestByteStream] as an API to your

4707

# configuration.

4708

"enabled": True or False, # Whether download is enabled.

4709

},

4710

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4711

# not contain an `additional_bindings` field themselves (that is,

4712

# the nesting may only be one level deep).

4713

# Object with schema name: HttpRule

4714

],

4715

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4716

# [][google.bytestream.RestByteStream] as an API to your

4717

# configuration.

4718

# [][google.bytestream.RestByteStream] as an API to your

4719

# configuration.

4720

"enabled": True or False, # Whether upload is enabled.

4721

},

4722

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

4723

"path": "A String", # The path matched by this custom verb.

4724

"kind": "A String", # The name of this custom HTTP verb.

4725

},

4726

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

4727

# response. Other response fields are ignored. This field is optional. When

4728

# not set, the response message will be used as HTTP body of response.

4729

# NOTE: the referred field must be not a repeated field and must be present

4730

# at the top-level of response message type.

4731

"put": "A String", # Used for updating a resource.

4732

"patch": "A String", # Used for updating a resource.

4733

"post": "A String", # Used for creating a resource.

4734

"selector": "A String", # Selects methods to which this rule applies.

4735

#

4736

# Refer to selector for syntax details.

4737

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4742

# of the google.protobuf.Api needs to be provided by the configuration

4743

# author, as the remaining fields will be derived from the IDL during the

4744

# normalization process. It is an error to specify an API interface here

4745

# which cannot be resolved against the associated IDL files.

4746

{ # Api is a light-weight descriptor for a protocol buffer service.

4747

"methods": [ # The methods of this api, in unspecified order.

4748

{ # Method represents a method of an api.

4749

"name": "A String", # The simple name of this method.

4750

"requestStreaming": True or False, # If true, the request is streamed.

4751

"responseTypeUrl": "A String", # The URL of the output message type.

4752

"requestTypeUrl": "A String", # A URL of the input message type.

4753

"responseStreaming": True or False, # If true, the response is streamed.

4754

"syntax": "A String", # The source syntax of this method.

4755

"options": [ # Any metadata attached to the method.

4756

{ # A protocol buffer option, which can be attached to a message, field,

4757

# enumeration, etc.

4758

"name": "A String", # The option's name. For example, `"java_package"`.

4759

"value": { # The option's value. For example, `"com.google.protobuf"`.

4760

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4767

# message.

4768

# protobuf element, like the file in which it is defined.

4769

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4770

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4771

},

4772

"mixins": [ # Included APIs. See Mixin.

4773

{ # Declares an API to be included in this API. The including API must

4774

# redeclare all the methods from the included API, but documentation

4775

# and options are inherited as follows:

4776

#

4777

# - If after comment and whitespace stripping, the documentation

4778

# string of the redeclared method is empty, it will be inherited

4779

# from the original method.

4780

#

4781

# - Each annotation belonging to the service config (http,

4782

# visibility) which is not set in the redeclared method will be

4783

# inherited.

4784

#

4785

# - If an http annotation is inherited, the path pattern will be

4786

# modified as follows. Any version prefix will be replaced by the

4787

# version of the including API plus the root path if specified.

4788

#

4789

# Example of a simple mixin:

4790

#

4791

# package google.acl.v1;

4792

# service AccessControl {

4793

# // Get the underlying ACL object.

4794

# rpc GetAcl(GetAclRequest) returns (Acl) {

4795

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4800

# service Storage {

4801

# // rpc GetAcl(GetAclRequest) returns (Acl);

4802

#

4803

# // Get a data record.

4804

# rpc GetData(GetDataRequest) returns (Data) {

4805

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4810

#

4811

# apis:

4812

# - name: google.storage.v2.Storage

4813

# mixins:

4814

# - name: google.acl.v1.AccessControl

4815

#

4816

# The mixin construct implies that all methods in `AccessControl` are

4817

# also declared with same name and request/response types in

4818

# `Storage`. A documentation generator or annotation processor will

4819

# see the effective `Storage.GetAcl` method after inherting

4820

# documentation and annotations as follows:

4821

#

4822

# service Storage {

4823

# // Get the underlying ACL object.

4824

# rpc GetAcl(GetAclRequest) returns (Acl) {

4825

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4831

#

4832

# If the `root` field in the mixin is specified, it should be a

4833

# relative path under which inherited HTTP paths are placed. Example:

4834

#

4835

# apis:

4836

# - name: google.storage.v2.Storage

4837

# mixins:

4838

# - name: google.acl.v1.AccessControl

4839

# root: acls

4840

#

4841

# This implies the following inherited HTTP annotation:

4842

#

4843

# service Storage {

4844

# // Get the underlying ACL object.

4845

# rpc GetAcl(GetAclRequest) returns (Acl) {

4846

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4851

# are rooted.

4852

"name": "A String", # The fully qualified name of the API which is included.

4853

},

4854

],

4855

"syntax": "A String", # The source syntax of the service.

4856

"version": "A String", # A version string for this api. If specified, must have the form

4857

# `major-version.minor-version`, as in `1.10`. If the minor version

4858

# is omitted, it defaults to zero. If the entire version field is

4859

# empty, the major version is derived from the package name, as

4860

# outlined below. If the field is not empty, the version in the

4861

# package name will be verified to be consistent with what is

4862

# provided here.

4863

#

4864

# The versioning schema uses [semantic

4865

# versioning](http://semver.org) where the major version number

4866

# indicates a breaking change and the minor version an additive,

4867

# non-breaking change. Both version numbers are signals to users

4868

# what to expect from different versions, and should be carefully

4869

# chosen based on the product plan.

4870

#

4871

# The major version is also reflected in the package name of the

4872

# API, which must end in `v<major-version>`, as in

4873

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4874

# be omitted. Zero major versions must only be used for

4875

# experimental, none-GA apis.

4876

"options": [ # Any metadata attached to the API.

4877

{ # A protocol buffer option, which can be attached to a message, field,

4878

# enumeration, etc.

4879

"name": "A String", # The option's name. For example, `"java_package"`.

4880

"value": { # The option's value. For example, `"com.google.protobuf"`.

4881

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

4886

# followed by the api's simple name.

4887

},

4888

],

4889

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4890

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

4898

# - google.foo.v1.AnotherError

4899

"rules": [ # The list of custom error rules that apply to individual API messages.

4900

#

4901

# **NOTE:** All service configuration rules follow "last one wins" order.

4902

{ # A custom error rule.

4903

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4904

# objects of this type will be filtered when they appear in error payload.

4905

"selector": "A String", # Selects messages to which this rule applies.

4906

#

4907

# Refer to selector for syntax details.

4908

},

4909

],

4910

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

4915

# elements. Restrictions are specified using visibility labels

4916

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

4917

#

4918

# Users and projects can have access to more than one visibility label. The

4919

# effective visibility for multiple labels is the union of each label's

4920

# elements, plus any unrestricted elements.

4921

#

4922

# If an element and its parents have no restrictions, visibility is

4923

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4930

# restriction: TRUSTED_TESTER

4931

# - selector: google.calendar.Calendar.Delegate

4932

# restriction: GOOGLE_INTERNAL

4933

#

4934

# Here, all methods are publicly visible except for the restricted methods

4935

# EnhancedSearch and Delegate.

4936

"rules": [ # A list of visibility rules that apply to individual API elements.

4937

#

4938

# **NOTE:** All service configuration rules follow "last one wins" order.

4939

{ # A visibility rule provides visibility configuration for an individual API

4940

# element.

4941

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

4942

# visibility to the element.

4943

#

4944

# If a rule has multiple labels, removing one of the labels but not all of

4945

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4952

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

4953

#

4954

# Removing GOOGLE_INTERNAL from this restriction will break clients that

4955

# rely on this method and only had access to it through GOOGLE_INTERNAL.

4956

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

4957

#

4958

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

4963

{ # Defines a metric type and its schema.

4964

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4965

# Use sentence case without an ending period, for example "Request count".

4966

"description": "A String", # A detailed description of the metric, which can be used in documentation.

4967

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

4968

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

4969

"labels": [ # The set of labels that can be used to describe a specific instance of this

4970

# metric type. For example, the

4971

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

4972

# has a label, `loadbalanced`, that specifies whether the traffic was

4973

# received through a load balanced IP address.

4974

{ # A description of a label.

4975

"valueType": "A String", # The type of data that can be assigned to the label.

4976

"description": "A String", # A human-readable description for the label.

4977

"key": "A String", # The label key.

4978

},

4979

],

4980

"type": "A String", # The metric type including a DNS name prefix, for example

4981

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

4982

# should use a natural hierarchical grouping such as the following:

4983

#

4984

# compute.googleapis.com/instance/cpu/utilization

4985

# compute.googleapis.com/instance/disk/read_ops_count

4986

# compute.googleapis.com/instance/network/received_bytes_count

4987

#

4988

# Note that if the metric type changes, the monitoring data will be

4989

# discontinued, and anything depends on it will break, such as monitoring

4990

# dashboards, alerting rules and quota limits. Therefore, once a metric has

4991

# been published, its type should be immutable.

4992

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

4993

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

4994

# supported units are a subset of [The Unified Code for Units of

4995

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4996

#

4997

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

5012

# * `P` peta (10**15)

5013

# * `E` exa (10**18)

5014

# * `Z` zetta (10**21)

5015

# * `Y` yotta (10**24)

5016

# * `m` milli (10**-3)

5017

# * `u` micro (10**-6)

5018

# * `n` nano (10**-9)

5019

# * `p` pico (10**-12)

5020

# * `f` femto (10**-15)

5021

# * `a` atto (10**-18)

5022

# * `z` zepto (10**-21)

5023

# * `y` yocto (10**-24)

5024

# * `Ki` kibi (2**10)

5025

# * `Mi` mebi (2**20)

5026

# * `Gi` gibi (2**30)

5027

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5032

#

5033

# The grammar also includes these connectors:

5034

#

5035

# * `/` division (as an infix operator, e.g. `1/s`).

5036

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5037

#

5038

# The grammar for a unit is as follows:

5039

#

5040

# Expression = Component { "." Component } { "/" Component } ;

5041

#

5042

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5052

# equivalent to `1` if it is used alone. For examples,

5053

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5054

# * `NAME` is a sequence of non-blank printable ASCII characters not

5055

# containing '{' or '}'.

5056

"name": "A String", # Resource name. The format of the name may vary between different

5057

# implementations. For examples:

5058

#

5059

# projects/{project_id}/metricDescriptors/{type=**}

5060

# metricDescriptors/{type=**}

5061

},

5062

],

5063

"enums": [ # A list of all enum types included in this API service. Enums

5064

# referenced directly or indirectly by the `apis` are automatically

5065

# included. Enums which are not referenced but shall be included

5066

# should be listed here by name. Example:

5067

#

5068

# enums:

5069

# - name: google.someapi.v1.SomeEnum

5070

{ # Enum type definition.

5071

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5072

# protobuf element, like the file in which it is defined.

5073

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5074

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5075

},

5076

"enumvalue": [ # Enum value definitions.

5077

{ # Enum value definition.

5078

"number": 42, # Enum value number.

5079

"options": [ # Protocol buffer options.

5080

{ # A protocol buffer option, which can be attached to a message, field,

5081

# enumeration, etc.

5082

"name": "A String", # The option's name. For example, `"java_package"`.

5083

"value": { # The option's value. For example, `"com.google.protobuf"`.

5084

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

5089

},

5090

],

5091

"options": [ # Protocol buffer options.

5092

{ # A protocol buffer option, which can be attached to a message, field,

5093

# enumeration, etc.

5094

"name": "A String", # The option's name. For example, `"java_package"`.

5095

"value": { # The option's value. For example, `"com.google.protobuf"`.

5096

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

5101

"syntax": "A String", # The source syntax.

5102

},

5103

],

5104

"types": [ # A list of all proto message types included in this API service.

5105

# Types referenced directly or indirectly by the `apis` are

5106

# automatically included. Messages which are not referenced but

5107

# shall be included, such as types used by the `google.protobuf.Any` type,

5108

# should be listed here by name. Example:

5109

#

5110

# types:

5111

# - name: google.protobuf.Int32

5112

{ # A protocol buffer message type.

5113

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5114

"A String",

5115

],

5116

"name": "A String", # The fully qualified message name.

5117

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5118

# protobuf element, like the file in which it is defined.

5119

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5120

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5121

},

5122

"syntax": "A String", # The source syntax.

5123

"fields": [ # The list of fields.

5124

{ # A single field of a message type.

5125

"kind": "A String", # The field type.

5126

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5127

# types. The first type has index 1; zero means the type is not in the list.

5128

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5129

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5130

"name": "A String", # The field name.

5131

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5132

"jsonName": "A String", # The field JSON name.

5133

"number": 42, # The field number.

5134

"cardinality": "A String", # The field cardinality.

5135

"options": [ # The protocol buffer options.

5136

{ # A protocol buffer option, which can be attached to a message, field,

5137

# enumeration, etc.

5138

"name": "A String", # The option's name. For example, `"java_package"`.

5139

"value": { # The option's value. For example, `"com.google.protobuf"`.

5140

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5145

},

5146

],

5147

"options": [ # The protocol buffer options.

5148

{ # A protocol buffer option, which can be attached to a message, field,

5149

# enumeration, etc.

5150

"name": "A String", # The option's name. For example, `"java_package"`.

5151

"value": { # The option's value. For example, `"com.google.protobuf"`.

5152

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

5159

#

5160

# The following example shows how to configure logs to be sent to the

5161

# producer and consumer projects. In the example,

5162

# the `library.googleapis.com/activity_history` log is

5163

# sent to both the producer and consumer projects, whereas

5164

# the `library.googleapis.com/purchase_history` log is only sent to the

5165

# producer project:

5166

#

5167

# monitored_resources:

5168

# - type: library.googleapis.com/branch

5169

# labels:

5170

# - key: /city

5171

# description: The city where the library branch is located in.

5172

# - key: /name

5173

# description: The name of the branch.

5174

# logs:

5175

# - name: library.googleapis.com/activity_history

5176

# labels:

5177

# - key: /customer_id

5178

# - name: library.googleapis.com/purchase_history

5179

# logging:

5180

# producer_destinations:

5181

# - monitored_resource: library.googleapis.com/branch

5182

# logs:

5183

# - library.googleapis.com/activity_history

5184

# - library.googleapis.com/purchase_history

5185

# consumer_destinations:

5186

# - monitored_resource: library.googleapis.com/branch

5187

# logs:

5188

# - library.googleapis.com/activity_history

5189

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5190

# There can be multiple producer destinations, each one must have a

5191

# different monitored resource type. A log can be used in at most

5192

# one producer destination.

5193

{ # Configuration of a specific logging destination (the producer project

5194

# or the consumer project).

5195

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5196

# Service.monitored_resources section.

5197

"logs": [ # Names of the logs to be sent to this destination. Each name must

5198

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5204

# There can be multiple consumer destinations, each one must have a

5205

# different monitored resource type. A log can be used in at most

5206

# one consumer destination.

5207

{ # Configuration of a specific logging destination (the producer project

5208

# or the consumer project).

5209

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5210

# Service.monitored_resources section.

5211

"logs": [ # Names of the logs to be sent to this destination. Each name must

5212

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

5219

# e.g. `calendar.googleapis.com`.

5220

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5221

#

5222

# Example:

5223

# <pre><code>documentation:

5224

# summary: >

5225

# The Google Calendar API gives access

5226

# to most calendar features.

5227

# pages:

5228

# - name: Overview

5229

# content: (== include google/foo/overview.md ==)

5230

# - name: Tutorial

5231

# content: (== include google/foo/tutorial.md ==)

5232

# subpages;

5233

# - name: Java

5234

# content: (== include google/foo/tutorial_java.md ==)

5235

# rules:

5236

# - selector: google.calendar.Calendar.Get

5237

# description: >

5238

# ...

5239

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5244

# standard markdown features, definition lists, tables and fenced

5245

# code blocks are supported. Section headers can be provided and are

5246

# interpreted relative to the section nesting of the context where

5247

# a documentation fragment is embedded.

5248

#

5249

# Documentation from the IDL is merged with documentation defined

5250

# via the config at normalization time, where documentation provided

5251

# by config rules overrides IDL provided.

5252

#

5253

# A number of constructs specific to the API platform are supported

5254

# in documentation text.

5255

#

5256

# In order to reference a proto element, the following

5257

# notation can be used:

5258

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5259

# To override the display text used for the link, this can be used:

5260

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5261

# Text can be excluded from doc using the following notation:

5262

# <pre><code>(-- internal comment --)</code></pre>

5263

# Comments can be made conditional using a visibility label. The below

5264

# text will be only rendered if the `BETA` label is available:

5265

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5266

# A few directives are available in documentation. Note that

5267

# directives must appear on a single line to be properly

5268

# identified. The `include` directive includes a markdown file from

5269

# an external source:

5270

# <pre><code>(== include path/to/file ==)</code></pre>

5271

# The `resource_for` directive marks a message to be the resource of

5272

# a collection in REST view. If it is not specified, tools attempt

5273

# to infer the resource from the operations in a collection:

5274

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5275

# The directive `suppress_warning` does not directly affect documentation

5276

# and is documented together with service config validation.

5277

"rules": [ # A list of documentation rules that apply to individual API elements.

5278

#

5279

# **NOTE:** All service configuration rules follow "last one wins" order.

5280

{ # A documentation rule provides information about individual API elements.

5281

"description": "A String", # Description of the selected API(s).

5282

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5283

# element is marked as `deprecated`.

5284

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5285

# qualified name of the element which may end in "*", indicating a wildcard.

5286

# Wildcards are only allowed at the end and for a whole component of the

5287

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5288

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

5293

# <pre><code>documentation:

5294

# summary: ...

5295

# overview: (== include overview.md ==)

5296

# </code></pre>

5297

# This is a shortcut for the following declaration (using pages style):

5298

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5303

# </code></pre>

5304

# Note: you cannot specify both `overview` field and `pages` field.

5305

"summary": "A String", # A short summary of what the service does. Can only be provided by

5306

# plain text.

5307

"pages": [ # The top level pages for the documentation set.

5308

{ # Represents a documentation page. A page can contain subpages to represent

5309

# nested documentation set structure.

5310

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5311

# to include content from a Markdown file.

5312

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5313

# honored in the generated docset.

5314

# Object with schema name: Page

5315

],

5316

"name": "A String", # The name of the page. It will be used as an identity of the page to

5317

# generate URI of the page, text of the link to this page in navigation,

5318

# etc. The full page name (start from the root page name to this page

5319

# concatenated with `.`) can be used as reference to the page in your

5320

# documentation. For example:

5321

# <pre><code>pages:

5322

# - name: Tutorial

5323

# content: (== include tutorial.md ==)

5324

# subpages:

5325

# - name: Java

5326

# content: (== include tutorial_java.md ==)

5327

# </code></pre>

5328

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

5333

},

5334

"systemTypes": [ # A list of all proto message types included in this API service.

5335

# It serves similar purpose as [google.api.Service.types], except that

5336

# these types are not needed by user-defined APIs. Therefore, they will not

5337

# show up in the generated discovery doc. This field should only be used

5338

# to define system APIs in ESF.

5339

{ # A protocol buffer message type.

5340

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5341

"A String",

5342

],

5343

"name": "A String", # The fully qualified message name.

5344

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5345

# protobuf element, like the file in which it is defined.

5346

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5347

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5348

},

5349

"syntax": "A String", # The source syntax.

5350

"fields": [ # The list of fields.

5351

{ # A single field of a message type.

5352

"kind": "A String", # The field type.

5353

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5354

# types. The first type has index 1; zero means the type is not in the list.

5355

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5356

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5357

"name": "A String", # The field name.

5358

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5359

"jsonName": "A String", # The field JSON name.

5360

"number": 42, # The field number.

5361

"cardinality": "A String", # The field cardinality.

5362

"options": [ # The protocol buffer options.

5363

{ # A protocol buffer option, which can be attached to a message, field,

5364

# enumeration, etc.

5365

"name": "A String", # The option's name. For example, `"java_package"`.

5366

"value": { # The option's value. For example, `"com.google.protobuf"`.

5367

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5372

},

5373

],

5374

"options": [ # The protocol buffer options.

5375

{ # A protocol buffer option, which can be attached to a message, field,

5376

# enumeration, etc.

5377

"name": "A String", # The option's name. For example, `"java_package"`.

5378

"value": { # The option's value. For example, `"com.google.protobuf"`.

5379

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

5394

# - google.rpc.context.OriginContext

5395

#

5396

# The above specifies that all methods in the API request

5397

# `google.rpc.context.ProjectContext` and

5398

# `google.rpc.context.OriginContext`.

5399

#

5400

# Available context types are defined in package

5401

# `google.rpc.context`.

5402

"rules": [ # A list of RPC context rules that apply to individual API methods.

5403

#

5404

# **NOTE:** All service configuration rules follow "last one wins" order.

5405

{ # A context rule provides information about the context for an individual API

5406

# element.

5407

"provided": [ # A list of full type names of provided contexts.

5408

"A String",

5409

],

5410

"requested": [ # A list of full type names of requested contexts.

5411

"A String",

5412

],

5413

"selector": "A String", # Selects the methods to which this rule applies.

5414

#

5415

# Refer to selector for syntax details.

},

],

},

},

],

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

5426

<pre>Retrieves the next page of results.

5427

5428

Args:

5429

previous_request: The request for the previous page. (required)

5430

previous_response: The response from the request for the previous page. (required)

5431

5432

Returns:

5433

A request object that you can call 'execute()' on to request the next

5434

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="submit">submit(serviceName=None, body, x__xgafv=None)</code>

5440

<pre>Creates a new service configuration (version) for a managed service based

5441

on

5442

user-supplied configuration source files (for example: OpenAPI

5443

Specification). This method stores the source configurations as well as the

5444

generated service configuration. To rollout the service configuration to

5445

other services,

5446

please call CreateServiceRollout.

5447

5448

Operation<response: SubmitConfigSourceResponse>

5449

5450

Args:

5451

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5452

for naming requirements. For example: `example.googleapis.com`. (required)

5453

body: object, The request body. (required)

5454

The object takes the form of:

5455

5456

{ # Request message for SubmitConfigSource method.

5457

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

5458

# `google.api.Service` configuration based on the `ConfigSource` provided,

5459

# but the generated config and the sources will NOT be persisted.

5460

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

5461

# defined by `google.api.Service`.

5462

"files": [ # Set of source configuration files that are used to generate a service

5463

# configuration (`google.api.Service`).

5464

{ # Generic specification of a source configuration file

5465

"fileContents": "A String", # The bytes that constitute the file.

5466

"fileType": "A String", # The type of configuration file this represents.

5467

"filePath": "A String", # The file name of the configuration file (full or relative path).

5468

},

5469

],

5470

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5471

# by the client for tracking purpose. If empty, the server may choose to

5472

# generate one instead.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5483

5484

{ # This resource represents a long-running operation that is the result of a

5485

# network API call.

5486

"metadata": { # Service-specific metadata associated with the operation. It typically

5487

# contains progress information and common metadata such as create time.

5488

# Some services might not provide such metadata. Any method that returns a

5489

# long-running operation should document the metadata type, if any.

5490

"a_key": "", # Properties of the object. Contains field @type with type URL.

5491

},

5492

"done": True or False, # If the value is `false`, it means the operation is still in progress.

5493

# If true, the operation is completed, and either `error` or `response` is

5494

# available.

5495

"response": { # The normal response of the operation in case of success. If the original

5496

# method returns no data on success, such as `Delete`, the response is

5497

# `google.protobuf.Empty`. If the original method is standard

5498

# `Get`/`Create`/`Update`, the response should be the resource. For other

5499

# methods, the response should have the type `XxxResponse`, where `Xxx`

5500

# is the original method name. For example, if the original method name

5501

# is `TakeSnapshot()`, the inferred response type is

5502

# `TakeSnapshotResponse`.

5503

"a_key": "", # Properties of the object. Contains field @type with type URL.

5504

},

5505

"name": "A String", # The server-assigned name, which is only unique within the same service that

5506

# originally returns it. If you use the default HTTP mapping, the

5507

# `name` should have the format of `operations/some/unique/name`.

5508

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure.

5509

# programming environments, including REST APIs and RPC APIs. It is used by

5510

# [gRPC](https://github.com/grpc). The error model is designed to be:

5511

#

5512

# - Simple to use and understand for most users

5513

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

5518

# and error details. The error code should be an enum value of

5519

# google.rpc.Code, but it may accept additional error codes if needed. The

5520

# error message should be a developer-facing English message that helps

5521

# developers *understand* and *resolve* the error. If a localized user-facing

5522

# error message is needed, put the localized message in the error details or

5523

# localize it in the client. The optional error details may contain arbitrary

5524

# information about the error. There is a predefined set of error detail types

5525

# in the package `google.rpc` which can be used for common error conditions.

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

5530

# is not necessarily the actual wire format. When the `Status` message is

5531

# exposed in different client libraries and different wire protocols, it can be

5532

# mapped differently. For example, it will likely be mapped to some exceptions

5533

# in Java, but more likely mapped to some error codes in C.

#

# # Other uses

#

# The error model and the `Status` message can be used in a variety of

5538

# environments, either with or without APIs, to provide a

5539

# consistent developer experience across different environments.

5540

#

5541

# Example uses of this error model include:

5542

#

5543

# - Partial errors. If a service needs to return partial errors to the client,

5544

# it may embed the `Status` in the normal response to indicate the partial

5545

# errors.

5546

#

5547

# - Workflow errors. A typical workflow has multiple steps. Each step may

5548

# have a `Status` message for error reporting purpose.

5549

#

5550

# - Batch operations. If a client uses batch request and batch response, the

5551

# `Status` message should be used directly inside batch response, one for

5552

# each error sub-response.

5553

#

5554

# - Asynchronous operations. If an API call embeds asynchronous operation

5555

# results in its response, the status of those operations should be

5556

# represented directly using the `Status` message.

5557

#

5558

# - Logging. If some API errors are stored in logs, the message `Status` could

5559

# be used directly after any stripping needed for security/privacy reasons.

5560

"message": "A String", # A developer-facing error message, which should be in English. Any

5561

# user-facing error message should be localized and sent in the

5562

# google.rpc.Status.details field, or localized by the client.

5563

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

5564

"details": [ # A list of messages that carry the error details. There will be a

5565

# common set of message types for APIs to use.

5566

{

5567

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

],

},

}</pre>

</div>

</body></html>