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

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

153

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

154

# without any article or other determiners. For example,

155

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

156

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

157

# be used in documentation.

158

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

159

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

160

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

161

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

162

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

163

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

164

},

165

],

166

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

167

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

168

#

169

# - name: library.googleapis.com/activity_history

170

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

171

# display_name: Activity

172

# labels:

173

# - key: /customer_id

174

# description: Identifier of a library customer

175

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

176

# Runtime requests that contain labels not specified here are

177

# considered invalid.

178

{ # A description of a label.

179

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

180

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

181

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

182

},

183

],

184

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

185

# the user interface and should be concise.

186

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

187

# the documentation and can contain details.

188

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

189

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

190

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

191

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

192

},

193

],

194

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

195

#

196

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

197

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

198

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

199

# change the names of the system parameters.

200

"rules": [ # Define system parameters.

201

#

202

# The parameters defined here will override the default parameters

203

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

204

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

205

# and names is implementation-dependent.

206

#

207

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

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

215

# - name: alt

216

# http_header: Response-Content-Type

217

#

218

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

223

# parameters:

224

# - name: api_key

225

# http_header: Api-Key1

226

# - name: api_key

227

# http_header: Api-Key2

228

#

229

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

230

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

231

# methods.

232

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

233

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

234

# names are used the behavior is implementation-dependent.

235

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

236

# parameter-dependent.

237

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

238

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

239

# is implementation-dependent.

240

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

241

# sensitive.

242

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

243

# and etc. It is case sensitive.

244

"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

249

# methods in all APIs.

250

#

251

# Refer to selector for syntax details.

},

],

},

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

256

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

257

#

258

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

259

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

260

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

261

#

262

# Refer to selector for syntax details.

263

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

264

# default depends on the deployment context.

265

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

},

],

},

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

270

#

271

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

272

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

273

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

274

# to both producer and consumer projects, whereas the

275

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

276

# consumer project.

277

#

278

# monitored_resources:

279

# - type: library.googleapis.com/branch

280

# labels:

281

# - key: /city

282

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

283

# - key: /name

284

# description: The name of the branch.

285

# metrics:

286

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

291

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

296

# monitoring:

297

# producer_destinations:

298

# - monitored_resource: library.googleapis.com/branch

299

# metrics:

300

# - library.googleapis.com/book/returned_count

301

# consumer_destinations:

302

# - monitored_resource: library.googleapis.com/branch

303

# metrics:

304

# - library.googleapis.com/book/returned_count

305

# - library.googleapis.com/book/overdue_count

306

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

307

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

308

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

309

# one producer destination.

310

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

311

# or the consumer project).

312

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

313

# Service.monitored_resources section.

314

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

315

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

"A String",

],

},

],

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

321

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

322

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

323

# one consumer destination.

324

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

325

# or the consumer project).

326

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

327

# Service.monitored_resources section.

328

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

329

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

"A String",

],

},

],

},

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

336

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

337

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

338

# generate one instead.

339

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

340

#

341

# Example for an API targeted for external use:

342

#

343

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

349

#

350

# - selector: google.calendar.Delegate

351

# oauth:

352

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

353

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

354

#

355

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

356

{ # Authentication rules for the service.

357

#

358

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

359

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

360

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

361

# request.

362

#

363

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

364

# ignored.

365

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

366

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

367

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

368

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

369

#

370

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

371

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

372

#

373

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

374

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

375

# the OAuth scope across all of those APIs.

376

#

377

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

378

# management about how developers will use them in practice.

379

#

380

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

381

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

382

# due to the backend requiring additional scopes or permissions.

383

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

384

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

#

# Example:

#

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

389

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

390

},

391

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

392

{ # User-defined authentication requirements, including support for

393

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

394

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

#

# Example:

#

# provider_id: bookstore_auth

399

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

400

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

401

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

402

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

403

# "https://Service_name/API_name"

404

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

405

# LibraryService API will only accept JWTs with the following audience

406

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

411

# bookstore_web.apps.googleusercontent.com

412

},

413

],

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

414

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

415

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

416

#

417

# For requests without credentials, if the service control environment is

418

# specified, each incoming request **must** be associated with a service

419

# consumer. This can be done by passing an API key that belongs to a consumer

420

# project.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

421

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

422

#

423

# Refer to selector for syntax details.

424

},

425

],

426

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

427

{ # Configuration for an anthentication provider, including support for

428

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

429

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

430

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

431

# Optional if the key set document:

432

# - can be retrieved from

433

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

434

# of the issuer.

435

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

436

#

437

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

438

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

439

# `AuthRequirement.provider_id`.

440

#

441

# Example: "bookstore_auth".

442

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

443

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

444

# Usually a URL or an email address.

445

#

446

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

447

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

},

],

},

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

452

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

453

#

454

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

455

{ # Usage configuration rules for the service.

456

#

457

# NOTE: Under development.

458

#

459

#

460

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

461

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

462

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

463

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

464

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

465

# allow/disallow unregistered calls.

466

#

467

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

473

#

474

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

#

# usage:

# rules:

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

479

# allow_unregistered_calls: true

480

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

481

# methods in all APIs.

482

#

483

# Refer to selector for syntax details.

484

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

485

},

486

],

487

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

488

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

489

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

"A String",

],

},

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

494

# influence interpretation of the configuration, for example, to

495

# determine defaults. This is documented together with applicable

496

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

497

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

498

# Members of this project can manage the service configuration,

499

# manage consumption of the service, etc.

500

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

501

# HttpRule, each specifying the mapping of an RPC method

502

# to one or more HTTP REST API methods.

503

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

504

#

505

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

506

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

507

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

508

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

509

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

510

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

511

# for details.

512

#

513

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

514

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

515

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

516

# operation on a resource collection of messages:

517

#

518

# ```proto

519

# service Messaging {

520

# rpc GetMessage(GetMessageRequest) returns (Message) {

521

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

522

# }

523

# }

524

# message GetMessageRequest {

525

# message SubMessage {

526

# string subfield = 1;

527

# }

528

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

529

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

530

# }

531

# message Message {

532

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

537

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

542

#

543

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

544

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

545

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

546

#

547

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

548

# pattern automatically become (optional) HTTP query

549

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

550

#

551

# ```proto

552

# message GetMessageRequest {

553

# message SubMessage {

554

# string subfield = 1;

555

# }

556

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

557

# int64 revision = 2; // becomes a parameter

558

# 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"))`

567

#

568

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

569

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

570

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

571

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

572

#

573

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

574

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

575

# message resource collection:

576

#

577

# ```proto

578

# service Messaging {

579

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

580

# option (google.api.http) = {

581

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

587

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

588

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

# }

# ```

#

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

593

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

594

# protos JSON encoding:

#

# HTTP | RPC

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

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

599

#

600

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

601

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

602

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

607

# rpc UpdateMessage(Message) returns (Message) {

608

# option (google.api.http) = {

609

# 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!")`

625

#

626

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

627

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

628

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

629

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

630

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

631

#

632

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

633

# the `additional_bindings` option. Example:

634

#

635

# ```proto

636

# service Messaging {

637

# rpc GetMessage(GetMessageRequest) returns (Message) {

638

# option (google.api.http) = {

639

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

640

# additional_bindings {

641

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

# }

# };

# }

# }

# message GetMessageRequest {

647

# string message_id = 1;

648

# 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")`

658

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

659

#

660

# # Rules for HTTP mapping

661

#

662

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

663

# to the request message are as follows:

664

#

665

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

666

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

667

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

668

# request) can be classified into three types:

669

# (a) Matched in the URL template.

670

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

671

# else everything under the body field)

672

# (c) All other fields.

673

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

674

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

675

#

676

# The syntax of the path template is as follows:

677

#

678

# Template = "/" Segments [ Verb ] ;

679

# Segments = Segment { "/" Segment } ;

680

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

681

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

682

# FieldPath = IDENT { "." IDENT } ;

683

# Verb = ":" LITERAL ;

684

#

685

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

686

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

687

# Expansion.

688

#

689

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

690

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

691

# Expansion.

692

#

693

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

694

#

695

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

696

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

697

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

698

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

699

#

700

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

701

# repeated fields or map fields.

702

#

703

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

704

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

705

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

706

# content to Web (HTML) clients.

707

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

708

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

709

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

710

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

711

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

712

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

713

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

714

# configuration.

715

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

716

# configuration.

717

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

718

},

719

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

720

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

721

# the nesting may only be one level deep).

722

# Object with schema name: HttpRule

723

],

724

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

725

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

726

# configuration.

727

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

728

# configuration.

729

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

730

},

731

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

732

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

733

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

734

},

735

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

736

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

737

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

738

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

739

# at the top-level of response message type.

740

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

741

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

742

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

743

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

744

#

745

# Refer to selector for syntax details.

746

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

},

],

},

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

751

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

752

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

753

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

754

# which cannot be resolved against the associated IDL files.

755

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

756

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

757

{ # Method represents a method of an api.

758

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

759

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

760

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

761

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

762

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

763

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

764

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

765

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

766

# enumeration, etc.

767

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

768

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

769

"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

776

# message.

777

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

778

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

779

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

780

},

781

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

782

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

783

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

784

# and options are inherited as follows:

785

#

786

# - If after comment and whitespace stripping, the documentation

787

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

788

# from the original method.

789

#

790

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

791

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

792

# inherited.

793

#

794

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

795

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

796

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

797

#

798

# Example of a simple mixin:

799

#

800

# package google.acl.v1;

801

# service AccessControl {

802

# // Get the underlying ACL object.

803

# rpc GetAcl(GetAclRequest) returns (Acl) {

804

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

# }

# }

#

# package google.storage.v2;

809

# service Storage {

810

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

811

#

812

# // Get a data record.

813

# rpc GetData(GetDataRequest) returns (Data) {

814

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

# }

# }

#

# Example of a mixin configuration:

819

#

820

# apis:

821

# - name: google.storage.v2.Storage

822

# mixins:

823

# - name: google.acl.v1.AccessControl

824

#

825

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

826

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

827

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

828

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

829

# documentation and annotations as follows:

830

#

831

# service Storage {

832

# // Get the underlying ACL object.

833

# rpc GetAcl(GetAclRequest) returns (Acl) {

834

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

# }

# ...

# }

#

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

840

#

841

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

842

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

843

#

844

# apis:

845

# - name: google.storage.v2.Storage

846

# mixins:

847

# - name: google.acl.v1.AccessControl

848

# root: acls

849

#

850

# This implies the following inherited HTTP annotation:

851

#

852

# service Storage {

853

# // Get the underlying ACL object.

854

# rpc GetAcl(GetAclRequest) returns (Acl) {

855

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

# }

# ...

# }

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

860

# are rooted.

861

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

862

},

863

],

864

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

865

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

866

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

867

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

868

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

869

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

870

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

871

# provided here.

872

#

873

# The versioning schema uses [semantic

874

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

875

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

876

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

877

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

878

# chosen based on the product plan.

879

#

880

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

881

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

882

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

883

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

884

# experimental, none-GA apis.

885

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

886

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

887

# enumeration, etc.

888

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

889

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

890

"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

895

# followed by the api's simple name.

896

},

897

],

898

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

899

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

907

# - google.foo.v1.AnotherError

908

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

909

#

910

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

911

{ # A custom error rule.

912

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

913

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

914

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

915

#

916

# Refer to selector for syntax details.

917

},

918

],

919

"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.

924

# elements. Restrictions are specified using visibility labels

925

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

926

#

927

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

928

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

929

# elements, plus any unrestricted elements.

930

#

931

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

932

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

939

# restriction: TRUSTED_TESTER

940

# - selector: google.calendar.Calendar.Delegate

941

# restriction: GOOGLE_INTERNAL

942

#

943

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

944

# EnhancedSearch and Delegate.

945

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

946

#

947

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

948

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

949

# element.

950

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

951

# visibility to the element.

952

#

953

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

954

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

961

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

962

#

963

# Removing GOOGLE_INTERNAL from this restriction will break clients that

964

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

965

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

966

#

967

# Refer to selector for syntax details.

},

],

},

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

972

{ # Defines a metric type and its schema.

973

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

974

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

975

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

976

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

977

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

978

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

979

# metric type. For example, the

980

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

981

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

982

# received through a load balanced IP address.

983

{ # A description of a label.

984

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

985

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

986

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

987

},

988

],

989

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

990

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

991

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

992

#

993

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

994

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

995

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

996

#

997

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

998

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

999

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

1000

# been published, its type should be immutable.

1001

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

1002

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

1003

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

1004

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

1005

#

1006

# **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)

1021

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

1022

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

1023

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

1024

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

1025

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

1026

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

1027

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

1028

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

1029

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

1030

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

1031

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

1032

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

1033

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

1034

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

1035

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

1036

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

#

# **Grammar**

#

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

1041

#

1042

# The grammar also includes these connectors:

1043

#

1044

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

1045

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

1046

#

1047

# The grammar for a unit is as follows:

1048

#

1049

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

1050

#

1051

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1061

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

1062

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

1063

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

1064

# containing '{' or '}'.

1065

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

1066

# implementations. For examples:

1067

#

1068

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

1069

# metricDescriptors/{type=**}

1070

},

1071

],

1072

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

1073

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

1074

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

1075

# should be listed here by name. Example:

1076

#

1077

# enums:

1078

# - name: google.someapi.v1.SomeEnum

1079

{ # Enum type definition.

1080

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

1081

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

1082

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

1083

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

1084

},

1085

"enumvalue": [ # Enum value definitions.

1086

{ # Enum value definition.

1087

"number": 42, # Enum value number.

1088

"options": [ # Protocol buffer options.

1089

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

1090

# enumeration, etc.

1091

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

1092

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

1093

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

},

},

],

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

1098

},

1099

],

1100

"options": [ # Protocol buffer options.

1101

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

1102

# enumeration, etc.

1103

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

1104

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

1105

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

},

},

],

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

1110

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

1111

},

1112

],

1113

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

1114

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

1115

# automatically included. Messages which are not referenced but

1116

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

1117

# should be listed here by name. Example:

1118

#

1119

# types:

1120

# - name: google.protobuf.Int32

1121

{ # A protocol buffer message type.

1122

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

1123

"A String",

1124

],

1125

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

1126

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

1127

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

1128

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

1129

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

1130

},

1131

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

1132

"fields": [ # The list of fields.

1133

{ # A single field of a message type.

1134

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

1135

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

1136

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

1137

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

1138

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

1139

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

1140

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

1141

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

1142

"number": 42, # The field number.

1143

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

1144

"options": [ # The protocol buffer options.

1145

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

1146

# enumeration, etc.

1147

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

1148

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

1149

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

},

},

],

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

1154

},

1155

],

1156

"options": [ # The protocol buffer options.

1157

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

1158

# enumeration, etc.

1159

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

1160

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

1161

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

},

},

],

},

],

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

1168

#

1169

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

1170

# producer and consumer projects. In the example,

1171

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

1172

# sent to both the producer and consumer projects, whereas

1173

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

1174

# producer project:

1175

#

1176

# monitored_resources:

1177

# - type: library.googleapis.com/branch

1178

# labels:

1179

# - key: /city

1180

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

1181

# - key: /name

1182

# description: The name of the branch.

1183

# logs:

1184

# - name: library.googleapis.com/activity_history

1185

# labels:

1186

# - key: /customer_id

1187

# - name: library.googleapis.com/purchase_history

1188

# logging:

1189

# producer_destinations:

1190

# - monitored_resource: library.googleapis.com/branch

1191

# logs:

1192

# - library.googleapis.com/activity_history

1193

# - library.googleapis.com/purchase_history

1194

# consumer_destinations:

1195

# - monitored_resource: library.googleapis.com/branch

1196

# logs:

1197

# - library.googleapis.com/activity_history

1198

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

1199

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

1200

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

1201

# one producer destination.

1202

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

1203

# or the consumer project).

1204

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

1205

# Service.monitored_resources section.

1206

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

1207

# be defined in the Service.logs section.

"A String",

],

},

],

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

1213

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

1214

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

1215

# one consumer destination.

1216

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

1217

# or the consumer project).

1218

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

1219

# Service.monitored_resources section.

1220

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

1221

# be defined in the Service.logs section.

"A String",

],

},

],

},

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

1228

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

1229

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

1230

#

1231

# Example:

1232

# <pre><code>documentation:

1233

# summary: >

1234

# The Google Calendar API gives access

1235

# to most calendar features.

1236

# pages:

1237

# - name: Overview

1238

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

1239

# - name: Tutorial

1240

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

1241

# subpages;

1242

# - name: Java

1243

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

1244

# rules:

1245

# - selector: google.calendar.Calendar.Get

1246

# description: >

1247

# ...

1248

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1253

# standard markdown features, definition lists, tables and fenced

1254

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

1255

# interpreted relative to the section nesting of the context where

1256

# a documentation fragment is embedded.

1257

#

1258

# Documentation from the IDL is merged with documentation defined

1259

# via the config at normalization time, where documentation provided

1260

# by config rules overrides IDL provided.

1261

#

1262

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

1263

# in documentation text.

1264

#

1265

# In order to reference a proto element, the following

1266

# notation can be used:

1267

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

1268

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

1269

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

1270

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

1271

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

1272

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

1273

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

1274

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

1275

# A few directives are available in documentation. Note that

1276

# directives must appear on a single line to be properly

1277

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

1278

# an external source:

1279

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

1280

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

1281

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

1282

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

1283

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

1284

# The directive `suppress_warning` does not directly affect documentation

1285

# and is documented together with service config validation.

1286

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

1287

#

1288

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

1289

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

1290

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

1291

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

1292

# element is marked as `deprecated`.

1293

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

1294

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

1295

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

1296

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

1297

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

# is used.

},

],

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

1302

# <pre><code>documentation:

1303

# summary: ...

1304

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

1305

# </code></pre>

1306

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

1307

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1312

# </code></pre>

1313

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

1314

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

1315

# plain text.

1316

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

1317

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

1318

# nested documentation set structure.

1319

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

1320

# to include content from a Markdown file.

1321

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

1322

# honored in the generated docset.

1323

# Object with schema name: Page

1324

],

1325

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

1326

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

1327

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

1328

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

1329

# documentation. For example:

1330

# <pre><code>pages:

1331

# - name: Tutorial

1332

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

1333

# subpages:

1334

# - name: Java

1335

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

1336

# </code></pre>

1337

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

# `Java`.

},

],

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

1342

},

1343

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

1344

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

1345

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

1346

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

1347

# to define system APIs in ESF.

1348

{ # A protocol buffer message type.

1349

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

1350

"A String",

1351

],

1352

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

1353

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

1354

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

1355

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

1356

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

1357

},

1358

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

1359

"fields": [ # The list of fields.

1360

{ # A single field of a message type.

1361

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

1362

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

1363

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

1364

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

1365

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

1366

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

1367

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

1368

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

1369

"number": 42, # The field number.

1370

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

1371

"options": [ # The protocol buffer options.

1372

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

1373

# enumeration, etc.

1374

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

1375

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

1376

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

},

},

],

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

1381

},

1382

],

1383

"options": [ # The protocol buffer options.

1384

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

1385

# enumeration, etc.

1386

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

1387

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

1388

"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

1403

# - google.rpc.context.OriginContext

1404

#

1405

# The above specifies that all methods in the API request

1406

# `google.rpc.context.ProjectContext` and

1407

# `google.rpc.context.OriginContext`.

1408

#

1409

# Available context types are defined in package

1410

# `google.rpc.context`.

1411

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

1412

#

1413

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

1414

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

1415

# element.

1416

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

1417

"A String",

1418

],

1419

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

1420

"A String",

1421

],

1422

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

1423

#

1424

# 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:

1437

1438

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

1439

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

1440

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

1446

# config_version: 1

1447

# name: calendar.googleapis.com

1448

# title: Google Calendar API

1449

# apis:

1450

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

1455

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

1456

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

1457

# monitoring, etc.

1458

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

1459

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

1460

},

1461

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

1462

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

1463

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

1464

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

1465

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

1466

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

1467

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

1468

#

1469

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

1470

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

1471

# by the API.

1472

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

1473

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

1474

# The maximum length of this value is 256 characters.

1475

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

1476

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

1477

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

1478

{ # A description of a label.

1479

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

1480

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

1481

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

1482

},

1483

],

1484

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

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

1485

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

1486

# without any article or other determiners. For example,

1487

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

1488

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

1489

# be used in documentation.

1490

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

1491

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

1492

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

1493

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

1494

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

1495

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

1496

},

1497

],

1498

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

1499

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

1500

#

1501

# - name: library.googleapis.com/activity_history

1502

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

1503

# display_name: Activity

1504

# labels:

1505

# - key: /customer_id

1506

# description: Identifier of a library customer

1507

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

1508

# Runtime requests that contain labels not specified here are

1509

# considered invalid.

1510

{ # A description of a label.

1511

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

1512

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

1513

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

1514

},

1515

],

1516

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

1517

# the user interface and should be concise.

1518

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

1519

# the documentation and can contain details.

1520

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

1521

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

1522

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

1523

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

1524

},

1525

],

1526

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

1527

#

1528

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

1529

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

1530

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

1531

# change the names of the system parameters.

1532

"rules": [ # Define system parameters.

1533

#

1534

# The parameters defined here will override the default parameters

1535

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

1536

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

1537

# and names is implementation-dependent.

1538

#

1539

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

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1547

# - name: alt

1548

# http_header: Response-Content-Type

1549

#

1550

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1555

# parameters:

1556

# - name: api_key

1557

# http_header: Api-Key1

1558

# - name: api_key

1559

# http_header: Api-Key2

1560

#

1561

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

1562

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

1563

# methods.

1564

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

1565

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

1566

# names are used the behavior is implementation-dependent.

1567

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

1568

# parameter-dependent.

1569

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

1570

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

1571

# is implementation-dependent.

1572

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

1573

# sensitive.

1574

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

1575

# and etc. It is case sensitive.

1576

"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

1581

# methods in all APIs.

1582

#

1583

# Refer to selector for syntax details.

},

],

},

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

1588

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

1589

#

1590

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

1591

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

1592

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

1593

#

1594

# Refer to selector for syntax details.

1595

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

1596

# default depends on the deployment context.

1597

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

},

],

},

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

1602

#

1603

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

1604

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

1605

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

1606

# to both producer and consumer projects, whereas the

1607

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

1608

# consumer project.

1609

#

1610

# monitored_resources:

1611

# - type: library.googleapis.com/branch

1612

# labels:

1613

# - key: /city

1614

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

1615

# - key: /name

1616

# description: The name of the branch.

1617

# metrics:

1618

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1623

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1628

# monitoring:

1629

# producer_destinations:

1630

# - monitored_resource: library.googleapis.com/branch

1631

# metrics:

1632

# - library.googleapis.com/book/returned_count

1633

# consumer_destinations:

1634

# - monitored_resource: library.googleapis.com/branch

1635

# metrics:

1636

# - library.googleapis.com/book/returned_count

1637

# - library.googleapis.com/book/overdue_count

1638

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

1639

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

1640

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

1641

# one producer destination.

1642

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

1643

# or the consumer project).

1644

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

1645

# Service.monitored_resources section.

1646

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

1647

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

"A String",

],

},

],

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

1653

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

1654

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

1655

# one consumer destination.

1656

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

1657

# or the consumer project).

1658

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

1659

# Service.monitored_resources section.

1660

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

1661

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

"A String",

],

},

],

},

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

1668

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

1669

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

1670

# generate one instead.

1671

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

1672

#

1673

# Example for an API targeted for external use:

1674

#

1675

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

1681

#

1682

# - selector: google.calendar.Delegate

1683

# oauth:

1684

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

1685

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

1686

#

1687

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

1688

{ # Authentication rules for the service.

1689

#

1690

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

1691

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

1692

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

1693

# request.

1694

#

1695

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

1696

# ignored.

1697

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

1698

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

1699

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

1700

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

1701

#

1702

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

1703

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

1704

#

1705

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

1706

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

1707

# the OAuth scope across all of those APIs.

1708

#

1709

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

1710

# management about how developers will use them in practice.

1711

#

1712

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

1713

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

1714

# due to the backend requiring additional scopes or permissions.

1715

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

1716

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

#

# Example:

#

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

1721

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

1722

},

1723

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

1724

{ # User-defined authentication requirements, including support for

1725

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

1726

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

#

# Example:

#

# provider_id: bookstore_auth

1731

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

1732

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

1733

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

1734

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

1735

# "https://Service_name/API_name"

1736

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

1737

# LibraryService API will only accept JWTs with the following audience

1738

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1743

# bookstore_web.apps.googleusercontent.com

1744

},

1745

],

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

1746

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

1747

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

1748

#

1749

# For requests without credentials, if the service control environment is

1750

# specified, each incoming request **must** be associated with a service

1751

# consumer. This can be done by passing an API key that belongs to a consumer

1752

# project.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

1753

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

1754

#

1755

# Refer to selector for syntax details.

1756

},

1757

],

1758

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

1759

{ # Configuration for an anthentication provider, including support for

1760

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

1761

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

1762

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

1763

# Optional if the key set document:

1764

# - can be retrieved from

1765

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

1766

# of the issuer.

1767

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

1768

#

1769

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

1770

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

1771

# `AuthRequirement.provider_id`.

1772

#

1773

# Example: "bookstore_auth".

1774

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

1775

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

1776

# Usually a URL or an email address.

1777

#

1778

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

1779

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

},

],

},

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

1784

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

1785

#

1786

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

1787

{ # Usage configuration rules for the service.

1788

#

1789

# NOTE: Under development.

1790

#

1791

#

1792

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

1793

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

1794

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

1795

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

1796

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

1797

# allow/disallow unregistered calls.

1798

#

1799

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1805

#

1806

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

#

# usage:

# rules:

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

1811

# allow_unregistered_calls: true

1812

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

1813

# methods in all APIs.

1814

#

1815

# Refer to selector for syntax details.

1816

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

1817

},

1818

],

1819

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

1820

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

1821

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

"A String",

],

},

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

1826

# influence interpretation of the configuration, for example, to

1827

# determine defaults. This is documented together with applicable

1828

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

1829

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

1830

# Members of this project can manage the service configuration,

1831

# manage consumption of the service, etc.

1832

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

1833

# HttpRule, each specifying the mapping of an RPC method

1834

# to one or more HTTP REST API methods.

1835

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

1836

#

1837

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

1838

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

1839

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

1840

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

1841

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

1842

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

1843

# for details.

1844

#

1845

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

1846

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

1847

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

1848

# operation on a resource collection of messages:

1849

#

1850

# ```proto

1851

# service Messaging {

1852

# rpc GetMessage(GetMessageRequest) returns (Message) {

1853

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

1854

# }

1855

# }

1856

# message GetMessageRequest {

1857

# message SubMessage {

1858

# string subfield = 1;

1859

# }

1860

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

1861

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

1862

# }

1863

# message Message {

1864

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

1869

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

1874

#

1875

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

1876

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

1877

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

1878

#

1879

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

1880

# pattern automatically become (optional) HTTP query

1881

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

1882

#

1883

# ```proto

1884

# message GetMessageRequest {

1885

# message SubMessage {

1886

# string subfield = 1;

1887

# }

1888

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

1889

# int64 revision = 2; // becomes a parameter

1890

# 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"))`

1899

#

1900

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

1901

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

1902

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

1903

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

1904

#

1905

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

1906

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

1907

# message resource collection:

1908

#

1909

# ```proto

1910

# service Messaging {

1911

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

1912

# option (google.api.http) = {

1913

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

1919

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

1920

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

# }

# ```

#

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

1925

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

1926

# protos JSON encoding:

#

# HTTP | RPC

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

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

1931

#

1932

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

1933

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

1934

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

1939

# rpc UpdateMessage(Message) returns (Message) {

1940

# option (google.api.http) = {

1941

# 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!")`

1957

#

1958

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

1959

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

1960

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

1961

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

1962

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

1963

#

1964

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

1965

# the `additional_bindings` option. Example:

1966

#

1967

# ```proto

1968

# service Messaging {

1969

# rpc GetMessage(GetMessageRequest) returns (Message) {

1970

# option (google.api.http) = {

1971

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

1972

# additional_bindings {

1973

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

# }

# };

# }

# }

# message GetMessageRequest {

1979

# string message_id = 1;

1980

# 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")`

1990

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

1991

#

1992

# # Rules for HTTP mapping

1993

#

1994

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

1995

# to the request message are as follows:

1996

#

1997

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

1998

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

1999

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

2000

# request) can be classified into three types:

2001

# (a) Matched in the URL template.

2002

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

2003

# else everything under the body field)

2004

# (c) All other fields.

2005

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

2006

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

2007

#

2008

# The syntax of the path template is as follows:

2009

#

2010

# Template = "/" Segments [ Verb ] ;

2011

# Segments = Segment { "/" Segment } ;

2012

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

2013

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

2014

# FieldPath = IDENT { "." IDENT } ;

2015

# Verb = ":" LITERAL ;

2016

#

2017

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

2018

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

2019

# Expansion.

2020

#

2021

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

2022

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

2023

# Expansion.

2024

#

2025

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

2026

#

2027

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

2028

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

2029

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

2030

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

2031

#

2032

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

2033

# repeated fields or map fields.

2034

#

2035

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

2036

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

2037

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

2038

# content to Web (HTML) clients.

2039

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

2040

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

2041

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

2042

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

2043

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

2044

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

2045

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

2046

# configuration.

2047

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

2048

# configuration.

2049

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

2050

},

2051

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

2052

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

2053

# the nesting may only be one level deep).

2054

# Object with schema name: HttpRule

2055

],

2056

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

2057

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

2058

# configuration.

2059

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

2060

# configuration.

2061

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

2062

},

2063

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

2064

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

2065

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

2066

},

2067

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

2068

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

2069

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

2070

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

2071

# at the top-level of response message type.

2072

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

2073

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

2074

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

2075

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

2076

#

2077

# Refer to selector for syntax details.

2078

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

},

],

},

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

2083

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

2084

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

2085

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

2086

# which cannot be resolved against the associated IDL files.

2087

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

2088

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

2089

{ # Method represents a method of an api.

2090

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

2091

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

2092

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

2093

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

2094

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

2095

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

2096

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

2097

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

2098

# enumeration, etc.

2099

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

2100

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

2101

"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

2108

# message.

2109

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

2110

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

2111

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

2112

},

2113

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

2114

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

2115

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

2116

# and options are inherited as follows:

2117

#

2118

# - If after comment and whitespace stripping, the documentation

2119

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

2120

# from the original method.

2121

#

2122

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

2123

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

2124

# inherited.

2125

#

2126

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

2127

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

2128

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

2129

#

2130

# Example of a simple mixin:

2131

#

2132

# package google.acl.v1;

2133

# service AccessControl {

2134

# // Get the underlying ACL object.

2135

# rpc GetAcl(GetAclRequest) returns (Acl) {

2136

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

# }

# }

#

# package google.storage.v2;

2141

# service Storage {

2142

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

2143

#

2144

# // Get a data record.

2145

# rpc GetData(GetDataRequest) returns (Data) {

2146

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

# }

# }

#

# Example of a mixin configuration:

2151

#

2152

# apis:

2153

# - name: google.storage.v2.Storage

2154

# mixins:

2155

# - name: google.acl.v1.AccessControl

2156

#

2157

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

2158

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

2159

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

2160

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

2161

# documentation and annotations as follows:

2162

#

2163

# service Storage {

2164

# // Get the underlying ACL object.

2165

# rpc GetAcl(GetAclRequest) returns (Acl) {

2166

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

# }

# ...

# }

#

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

2172

#

2173

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

2174

# relative path under which inherited HTTP paths are placed. Example:

2175

#

2176

# apis:

2177

# - name: google.storage.v2.Storage

2178

# mixins:

2179

# - name: google.acl.v1.AccessControl

2180

# root: acls

2181

#

2182

# This implies the following inherited HTTP annotation:

2183

#

2184

# service Storage {

2185

# // Get the underlying ACL object.

2186

# rpc GetAcl(GetAclRequest) returns (Acl) {

2187

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2192

# are rooted.

2193

"name": "A String", # The fully qualified name of the API which is included.

2194

},

2195

],

2196

"syntax": "A String", # The source syntax of the service.

2197

"version": "A String", # A version string for this api. If specified, must have the form

2198

# `major-version.minor-version`, as in `1.10`. If the minor version

2199

# is omitted, it defaults to zero. If the entire version field is

2200

# empty, the major version is derived from the package name, as

2201

# outlined below. If the field is not empty, the version in the

2202

# package name will be verified to be consistent with what is

2203

# provided here.

2204

#

2205

# The versioning schema uses [semantic

2206

# versioning](http://semver.org) where the major version number

2207

# indicates a breaking change and the minor version an additive,

2208

# non-breaking change. Both version numbers are signals to users

2209

# what to expect from different versions, and should be carefully

2210

# chosen based on the product plan.

2211

#

2212

# The major version is also reflected in the package name of the

2213

# API, which must end in `v<major-version>`, as in

2214

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2215

# be omitted. Zero major versions must only be used for

2216

# experimental, none-GA apis.

2217

"options": [ # Any metadata attached to the API.

2218

{ # A protocol buffer option, which can be attached to a message, field,

2219

# enumeration, etc.

2220

"name": "A String", # The option's name. For example, `"java_package"`.

2221

"value": { # The option's value. For example, `"com.google.protobuf"`.

2222

"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

2227

# followed by the api's simple name.

2228

},

2229

],

2230

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2231

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2239

# - google.foo.v1.AnotherError

2240

"rules": [ # The list of custom error rules that apply to individual API messages.

2241

#

2242

# **NOTE:** All service configuration rules follow "last one wins" order.

2243

{ # A custom error rule.

2244

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2245

# objects of this type will be filtered when they appear in error payload.

2246

"selector": "A String", # Selects messages to which this rule applies.

2247

#

2248

# Refer to selector for syntax details.

2249

},

2250

],

2251

"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.

2256

# elements. Restrictions are specified using visibility labels

2257

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2258

#

2259

# Users and projects can have access to more than one visibility label. The

2260

# effective visibility for multiple labels is the union of each label's

2261

# elements, plus any unrestricted elements.

2262

#

2263

# If an element and its parents have no restrictions, visibility is

2264

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2271

# restriction: TRUSTED_TESTER

2272

# - selector: google.calendar.Calendar.Delegate

2273

# restriction: GOOGLE_INTERNAL

2274

#

2275

# Here, all methods are publicly visible except for the restricted methods

2276

# EnhancedSearch and Delegate.

2277

"rules": [ # A list of visibility rules that apply to individual API elements.

2278

#

2279

# **NOTE:** All service configuration rules follow "last one wins" order.

2280

{ # A visibility rule provides visibility configuration for an individual API

2281

# element.

2282

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

2283

# visibility to the element.

2284

#

2285

# If a rule has multiple labels, removing one of the labels but not all of

2286

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2293

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2294

#

2295

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2296

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2297

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2298

#

2299

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

2304

{ # Defines a metric type and its schema.

2305

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2306

# Use sentence case without an ending period, for example "Request count".

2307

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2308

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

2309

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

2310

"labels": [ # The set of labels that can be used to describe a specific instance of this

2311

# metric type. For example, the

2312

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

2313

# has a label, `loadbalanced`, that specifies whether the traffic was

2314

# received through a load balanced IP address.

2315

{ # A description of a label.

2316

"valueType": "A String", # The type of data that can be assigned to the label.

2317

"description": "A String", # A human-readable description for the label.

2318

"key": "A String", # The label key.

2319

},

2320

],

2321

"type": "A String", # The metric type including a DNS name prefix, for example

2322

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

2323

# should use a natural hierarchical grouping such as the following:

2324

#

2325

# compute.googleapis.com/instance/cpu/utilization

2326

# compute.googleapis.com/instance/disk/read_ops_count

2327

# compute.googleapis.com/instance/network/received_bytes_count

2328

#

2329

# Note that if the metric type changes, the monitoring data will be

2330

# discontinued, and anything depends on it will break, such as monitoring

2331

# dashboards, alerting rules and quota limits. Therefore, once a metric has

2332

# been published, its type should be immutable.

2333

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2334

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2335

# supported units are a subset of [The Unified Code for Units of

2336

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2337

#

2338

# **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)

2353

# * `P` peta (10**15)

2354

# * `E` exa (10**18)

2355

# * `Z` zetta (10**21)

2356

# * `Y` yotta (10**24)

2357

# * `m` milli (10**-3)

2358

# * `u` micro (10**-6)

2359

# * `n` nano (10**-9)

2360

# * `p` pico (10**-12)

2361

# * `f` femto (10**-15)

2362

# * `a` atto (10**-18)

2363

# * `z` zepto (10**-21)

2364

# * `y` yocto (10**-24)

2365

# * `Ki` kibi (2**10)

2366

# * `Mi` mebi (2**20)

2367

# * `Gi` gibi (2**30)

2368

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2373

#

2374

# The grammar also includes these connectors:

2375

#

2376

# * `/` division (as an infix operator, e.g. `1/s`).

2377

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2378

#

2379

# The grammar for a unit is as follows:

2380

#

2381

# Expression = Component { "." Component } { "/" Component } ;

2382

#

2383

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2393

# equivalent to `1` if it is used alone. For examples,

2394

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2395

# * `NAME` is a sequence of non-blank printable ASCII characters not

2396

# containing '{' or '}'.

2397

"name": "A String", # Resource name. The format of the name may vary between different

2398

# implementations. For examples:

2399

#

2400

# projects/{project_id}/metricDescriptors/{type=**}

2401

# metricDescriptors/{type=**}

2402

},

2403

],

2404

"enums": [ # A list of all enum types included in this API service. Enums

2405

# referenced directly or indirectly by the `apis` are automatically

2406

# included. Enums which are not referenced but shall be included

2407

# should be listed here by name. Example:

2408

#

2409

# enums:

2410

# - name: google.someapi.v1.SomeEnum

2411

{ # Enum type definition.

2412

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2413

# protobuf element, like the file in which it is defined.

2414

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2415

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2416

},

2417

"enumvalue": [ # Enum value definitions.

2418

{ # Enum value definition.

2419

"number": 42, # Enum value number.

2420

"options": [ # Protocol buffer options.

2421

{ # A protocol buffer option, which can be attached to a message, field,

2422

# enumeration, etc.

2423

"name": "A String", # The option's name. For example, `"java_package"`.

2424

"value": { # The option's value. For example, `"com.google.protobuf"`.

2425

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

2430

},

2431

],

2432

"options": [ # Protocol buffer options.

2433

{ # A protocol buffer option, which can be attached to a message, field,

2434

# enumeration, etc.

2435

"name": "A String", # The option's name. For example, `"java_package"`.

2436

"value": { # The option's value. For example, `"com.google.protobuf"`.

2437

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2442

"syntax": "A String", # The source syntax.

2443

},

2444

],

2445

"types": [ # A list of all proto message types included in this API service.

2446

# Types referenced directly or indirectly by the `apis` are

2447

# automatically included. Messages which are not referenced but

2448

# shall be included, such as types used by the `google.protobuf.Any` type,

2449

# should be listed here by name. Example:

2450

#

2451

# types:

2452

# - name: google.protobuf.Int32

2453

{ # A protocol buffer message type.

2454

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2455

"A String",

2456

],

2457

"name": "A String", # The fully qualified message name.

2458

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2459

# protobuf element, like the file in which it is defined.

2460

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2461

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2462

},

2463

"syntax": "A String", # The source syntax.

2464

"fields": [ # The list of fields.

2465

{ # A single field of a message type.

2466

"kind": "A String", # The field type.

2467

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2468

# types. The first type has index 1; zero means the type is not in the list.

2469

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2470

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2471

"name": "A String", # The field name.

2472

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2473

"jsonName": "A String", # The field JSON name.

2474

"number": 42, # The field number.

2475

"cardinality": "A String", # The field cardinality.

2476

"options": [ # The protocol buffer options.

2477

{ # A protocol buffer option, which can be attached to a message, field,

2478

# enumeration, etc.

2479

"name": "A String", # The option's name. For example, `"java_package"`.

2480

"value": { # The option's value. For example, `"com.google.protobuf"`.

2481

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2486

},

2487

],

2488

"options": [ # The protocol buffer options.

2489

{ # A protocol buffer option, which can be attached to a message, field,

2490

# enumeration, etc.

2491

"name": "A String", # The option's name. For example, `"java_package"`.

2492

"value": { # The option's value. For example, `"com.google.protobuf"`.

2493

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

2500

#

2501

# The following example shows how to configure logs to be sent to the

2502

# producer and consumer projects. In the example,

2503

# the `library.googleapis.com/activity_history` log is

2504

# sent to both the producer and consumer projects, whereas

2505

# the `library.googleapis.com/purchase_history` log is only sent to the

2506

# producer project:

2507

#

2508

# monitored_resources:

2509

# - type: library.googleapis.com/branch

2510

# labels:

2511

# - key: /city

2512

# description: The city where the library branch is located in.

2513

# - key: /name

2514

# description: The name of the branch.

2515

# logs:

2516

# - name: library.googleapis.com/activity_history

2517

# labels:

2518

# - key: /customer_id

2519

# - name: library.googleapis.com/purchase_history

2520

# logging:

2521

# producer_destinations:

2522

# - monitored_resource: library.googleapis.com/branch

2523

# logs:

2524

# - library.googleapis.com/activity_history

2525

# - library.googleapis.com/purchase_history

2526

# consumer_destinations:

2527

# - monitored_resource: library.googleapis.com/branch

2528

# logs:

2529

# - library.googleapis.com/activity_history

2530

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2531

# There can be multiple producer destinations, each one must have a

2532

# different monitored resource type. A log can be used in at most

2533

# one producer 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",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

2545

# There can be multiple consumer destinations, each one must have a

2546

# different monitored resource type. A log can be used in at most

2547

# one consumer destination.

2548

{ # Configuration of a specific logging destination (the producer project

2549

# or the consumer project).

2550

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2551

# Service.monitored_resources section.

2552

"logs": [ # Names of the logs to be sent to this destination. Each name must

2553

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

2560

# e.g. `calendar.googleapis.com`.

2561

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2562

#

2563

# Example:

2564

# <pre><code>documentation:

2565

# summary: >

2566

# The Google Calendar API gives access

2567

# to most calendar features.

2568

# pages:

2569

# - name: Overview

2570

# content: (== include google/foo/overview.md ==)

2571

# - name: Tutorial

2572

# content: (== include google/foo/tutorial.md ==)

2573

# subpages;

2574

# - name: Java

2575

# content: (== include google/foo/tutorial_java.md ==)

2576

# rules:

2577

# - selector: google.calendar.Calendar.Get

2578

# description: >

2579

# ...

2580

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2585

# standard markdown features, definition lists, tables and fenced

2586

# code blocks are supported. Section headers can be provided and are

2587

# interpreted relative to the section nesting of the context where

2588

# a documentation fragment is embedded.

2589

#

2590

# Documentation from the IDL is merged with documentation defined

2591

# via the config at normalization time, where documentation provided

2592

# by config rules overrides IDL provided.

2593

#

2594

# A number of constructs specific to the API platform are supported

2595

# in documentation text.

2596

#

2597

# In order to reference a proto element, the following

2598

# notation can be used:

2599

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2600

# To override the display text used for the link, this can be used:

2601

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2602

# Text can be excluded from doc using the following notation:

2603

# <pre><code>(-- internal comment --)</code></pre>

2604

# Comments can be made conditional using a visibility label. The below

2605

# text will be only rendered if the `BETA` label is available:

2606

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2607

# A few directives are available in documentation. Note that

2608

# directives must appear on a single line to be properly

2609

# identified. The `include` directive includes a markdown file from

2610

# an external source:

2611

# <pre><code>(== include path/to/file ==)</code></pre>

2612

# The `resource_for` directive marks a message to be the resource of

2613

# a collection in REST view. If it is not specified, tools attempt

2614

# to infer the resource from the operations in a collection:

2615

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2616

# The directive `suppress_warning` does not directly affect documentation

2617

# and is documented together with service config validation.

2618

"rules": [ # A list of documentation rules that apply to individual API elements.

2619

#

2620

# **NOTE:** All service configuration rules follow "last one wins" order.

2621

{ # A documentation rule provides information about individual API elements.

2622

"description": "A String", # Description of the selected API(s).

2623

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2624

# element is marked as `deprecated`.

2625

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2626

# qualified name of the element which may end in "*", indicating a wildcard.

2627

# Wildcards are only allowed at the end and for a whole component of the

2628

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2629

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

2634

# <pre><code>documentation:

2635

# summary: ...

2636

# overview: (== include overview.md ==)

2637

# </code></pre>

2638

# This is a shortcut for the following declaration (using pages style):

2639

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2644

# </code></pre>

2645

# Note: you cannot specify both `overview` field and `pages` field.

2646

"summary": "A String", # A short summary of what the service does. Can only be provided by

2647

# plain text.

2648

"pages": [ # The top level pages for the documentation set.

2649

{ # Represents a documentation page. A page can contain subpages to represent

2650

# nested documentation set structure.

2651

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2652

# to include content from a Markdown file.

2653

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2654

# honored in the generated docset.

2655

# Object with schema name: Page

2656

],

2657

"name": "A String", # The name of the page. It will be used as an identity of the page to

2658

# generate URI of the page, text of the link to this page in navigation,

2659

# etc. The full page name (start from the root page name to this page

2660

# concatenated with `.`) can be used as reference to the page in your

2661

# documentation. For example:

2662

# <pre><code>pages:

2663

# - name: Tutorial

2664

# content: (== include tutorial.md ==)

2665

# subpages:

2666

# - name: Java

2667

# content: (== include tutorial_java.md ==)

2668

# </code></pre>

2669

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

2674

},

2675

"systemTypes": [ # A list of all proto message types included in this API service.

2676

# It serves similar purpose as [google.api.Service.types], except that

2677

# these types are not needed by user-defined APIs. Therefore, they will not

2678

# show up in the generated discovery doc. This field should only be used

2679

# to define system APIs in ESF.

2680

{ # A protocol buffer message type.

2681

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2682

"A String",

2683

],

2684

"name": "A String", # The fully qualified message name.

2685

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2686

# protobuf element, like the file in which it is defined.

2687

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2688

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2689

},

2690

"syntax": "A String", # The source syntax.

2691

"fields": [ # The list of fields.

2692

{ # A single field of a message type.

2693

"kind": "A String", # The field type.

2694

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2695

# types. The first type has index 1; zero means the type is not in the list.

2696

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2697

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2698

"name": "A String", # The field name.

2699

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2700

"jsonName": "A String", # The field JSON name.

2701

"number": 42, # The field number.

2702

"cardinality": "A String", # The field cardinality.

2703

"options": [ # The protocol buffer options.

2704

{ # A protocol buffer option, which can be attached to a message, field,

2705

# enumeration, etc.

2706

"name": "A String", # The option's name. For example, `"java_package"`.

2707

"value": { # The option's value. For example, `"com.google.protobuf"`.

2708

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2713

},

2714

],

2715

"options": [ # The protocol buffer options.

2716

{ # A protocol buffer option, which can be attached to a message, field,

2717

# enumeration, etc.

2718

"name": "A String", # The option's name. For example, `"java_package"`.

2719

"value": { # The option's value. For example, `"com.google.protobuf"`.

2720

"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

2735

# - google.rpc.context.OriginContext

2736

#

2737

# The above specifies that all methods in the API request

2738

# `google.rpc.context.ProjectContext` and

2739

# `google.rpc.context.OriginContext`.

2740

#

2741

# Available context types are defined in package

2742

# `google.rpc.context`.

2743

"rules": [ # A list of RPC context rules that apply to individual API methods.

2744

#

2745

# **NOTE:** All service configuration rules follow "last one wins" order.

2746

{ # A context rule provides information about the context for an individual API

2747

# element.

2748

"provided": [ # A list of full type names of provided contexts.

2749

"A String",

2750

],

2751

"requested": [ # A list of full type names of requested contexts.

2752

"A String",

2753

],

2754

"selector": "A String", # Selects the methods to which this rule applies.

2755

#

2756

# Refer to selector for syntax details.

},

],

},

}</pre>

</div>

<code class="details" id="get">get(serviceName=None, configId, x__xgafv=None)</code>

2765

<pre>Gets a service configuration (version) for a managed service.

2766

2767

Args:

2768

serviceName: string, The name of the service. See the [overview](/service-management/overview)

2769

for naming requirements. For example: `example.googleapis.com`. (required)

2770

configId: string, A parameter (required)

2771

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2778

2779

{ # `Service` is the root object of the configuration schema. It

2780

# describes basic information like the name of the service and the

2781

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

2787

# config_version: 1

2788

# name: calendar.googleapis.com

2789

# title: Google Calendar API

2790

# apis:

2791

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

2796

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2797

# service controller handles features like abuse, quota, billing, logging,

2798

# monitoring, etc.

2799

"environment": "A String", # The service control environment to use. If empty, no control plane

2800

# feature (like quota and billing) will be enabled.

2801

},

2802

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

2803

# by the Service.monitoring and Service.logging configurations.

2804

{ # An object that describes the schema of a MonitoredResource object using a

2805

# type name and a set of labels. For example, the monitored resource

2806

# descriptor for Google Compute Engine VM instances has a type of

2807

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

2808

# `"zone"` to identify particular VM instances.

2809

#

2810

# Different APIs can support different monitored resource types. APIs generally

2811

# provide a `list` method that returns the monitored resource descriptors used

2812

# by the API.

2813

"type": "A String", # Required. The monitored resource type. For example, the type

2814

# `"cloudsql_database"` represents databases in Google Cloud SQL.

2815

# The maximum length of this value is 256 characters.

2816

"labels": [ # Required. A set of labels used to describe instances of this monitored

2817

# resource type. For example, an individual Google Cloud SQL database is

2818

# identified by values for the labels `"database_id"` and `"zone"`.

2819

{ # A description of a label.

2820

"valueType": "A String", # The type of data that can be assigned to the label.

2821

"description": "A String", # A human-readable description for the label.

2822

"key": "A String", # The label key.

2823

},

2824

],

2825

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

2826

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

2827

# without any article or other determiners. For example,

2828

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

2829

"description": "A String", # Optional. A detailed description of the monitored resource type that might

2830

# be used in documentation.

2831

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

2832

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

2833

# {type} is the value of the `type` field in this object and

2834

# {project_id} is a project ID that provides API-specific context for

2835

# accessing the type. APIs that do not use project information can use the

2836

# resource name format `"monitoredResourceDescriptors/{type}"`.

2837

},

2838

],

2839

"logs": [ # Defines the logs used by this service.

2840

{ # A description of a log type. Example in YAML format:

2841

#

2842

# - name: library.googleapis.com/activity_history

2843

# description: The history of borrowing and returning library items.

2844

# display_name: Activity

2845

# labels:

2846

# - key: /customer_id

2847

# description: Identifier of a library customer

2848

"labels": [ # The set of labels that are available to describe a specific log entry.

2849

# Runtime requests that contain labels not specified here are

2850

# considered invalid.

2851

{ # A description of a label.

2852

"valueType": "A String", # The type of data that can be assigned to the label.

2853

"description": "A String", # A human-readable description for the label.

2854

"key": "A String", # The label key.

2855

},

2856

],

2857

"displayName": "A String", # The human-readable name for this log. This information appears on

2858

# the user interface and should be concise.

2859

"description": "A String", # A human-readable description of this log. This information appears in

2860

# the documentation and can contain details.

2861

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2862

# include the following characters: upper- and lower-case alphanumeric

2863

# characters [A-Za-z0-9], and punctuation characters including

2864

# slash, underscore, hyphen, period [/_-.].

2865

},

2866

],

2867

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

2868

#

2869

# A system parameter is a special kind of parameter defined by the API

2870

# system, not by an individual API. It is typically mapped to an HTTP header

2871

# and/or a URL query parameter. This configuration specifies which methods

2872

# change the names of the system parameters.

2873

"rules": [ # Define system parameters.

2874

#

2875

# The parameters defined here will override the default parameters

2876

# implemented by the system. If this field is missing from the service

2877

# config, default system parameters will be used. Default system parameters

2878

# and names is implementation-dependent.

2879

#

2880

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

2888

# - name: alt

2889

# http_header: Response-Content-Type

2890

#

2891

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

2896

# parameters:

2897

# - name: api_key

2898

# http_header: Api-Key1

2899

# - name: api_key

2900

# http_header: Api-Key2

2901

#

2902

# **NOTE:** All service configuration rules follow "last one wins" order.

2903

{ # Define a system parameter rule mapping system parameter definitions to

2904

# methods.

2905

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

2906

# For a given method call, only one of them should be used. If multiple

2907

# names are used the behavior is implementation-dependent.

2908

# If none of the specified names are present the behavior is

2909

# parameter-dependent.

2910

{ # Define a parameter's name and location. The parameter may be passed as either

2911

# an HTTP header or a URL query parameter, and if both are passed the behavior

2912

# is implementation-dependent.

2913

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

2914

# sensitive.

2915

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

2916

# and etc. It is case sensitive.

2917

"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

2922

# methods in all APIs.

2923

#

2924

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

2929

"rules": [ # A list of API backend rules that apply to individual API methods.

2930

#

2931

# **NOTE:** All service configuration rules follow "last one wins" order.

2932

{ # A backend rule provides configuration for an individual API element.

2933

"selector": "A String", # Selects the methods to which this rule applies.

2934

#

2935

# Refer to selector for syntax details.

2936

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

2937

# default depends on the deployment context.

2938

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

2943

#

2944

# The example below shows how to configure monitored resources and metrics

2945

# for monitoring. In the example, a monitored resource and two metrics are

2946

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2947

# to both producer and consumer projects, whereas the

2948

# `library.googleapis.com/book/overdue_count` metric is only sent to the

2949

# consumer project.

2950

#

2951

# monitored_resources:

2952

# - type: library.googleapis.com/branch

2953

# labels:

2954

# - key: /city

2955

# description: The city where the library branch is located in.

2956

# - key: /name

2957

# description: The name of the branch.

2958

# metrics:

2959

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2964

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2969

# monitoring:

2970

# producer_destinations:

2971

# - monitored_resource: library.googleapis.com/branch

2972

# metrics:

2973

# - library.googleapis.com/book/returned_count

2974

# consumer_destinations:

2975

# - monitored_resource: library.googleapis.com/branch

2976

# metrics:

2977

# - library.googleapis.com/book/returned_count

2978

# - library.googleapis.com/book/overdue_count

2979

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

2980

# There can be multiple producer destinations, each one must have a

2981

# different monitored resource type. A metric can be used in at most

2982

# one producer destination.

2983

{ # Configuration of a specific monitoring destination (the producer project

2984

# or the consumer project).

2985

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2986

# Service.monitored_resources section.

2987

"metrics": [ # Names of the metrics to report to this monitoring destination.

2988

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

2994

# There can be multiple consumer destinations, each one must have a

2995

# different monitored resource type. A metric can be used in at most

2996

# one consumer destination.

2997

{ # Configuration of a specific monitoring destination (the producer project

2998

# or the consumer project).

2999

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3000

# Service.monitored_resources section.

3001

"metrics": [ # Names of the metrics to report to this monitoring destination.

3002

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

3009

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3010

# by the client for tracking purpose. If empty, the server may choose to

3011

# generate one instead.

3012

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3013

#

3014

# Example for an API targeted for external use:

3015

#

3016

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

3022

#

3023

# - selector: google.calendar.Delegate

3024

# oauth:

3025

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

3026

"rules": [ # A list of authentication rules that apply to individual API methods.

3027

#

3028

# **NOTE:** All service configuration rules follow "last one wins" order.

3029

{ # Authentication rules for the service.

3030

#

3031

# By default, if a method has any authentication requirements, every request

3032

# must include a valid credential matching one of the requirements.

3033

# It's an error to include more than one kind of credential in a single

3034

# request.

3035

#

3036

# If a method doesn't have any auth requirements, request credentials will be

3037

# ignored.

3038

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3039

# there are scopes defined for "Read-only access to Google Calendar" and

3040

# "Access to Cloud Platform". Users can consent to a scope for an application,

3041

# giving it permission to access that data on their behalf.

3042

#

3043

# OAuth scope specifications should be fairly coarse grained; a user will need

3044

# to see and understand the text description of what your scope means.

3045

#

3046

# In most cases: use one or at most two OAuth scopes for an entire family of

3047

# products. If your product has multiple APIs, you should probably be sharing

3048

# the OAuth scope across all of those APIs.

3049

#

3050

# When you need finer grained OAuth consent screens: talk with your product

3051

# management about how developers will use them in practice.

3052

#

3053

# Please note that even though each of the canonical scopes is enough for a

3054

# request to be accepted and passed to the backend, a request can still fail

3055

# due to the backend requiring additional scopes or permissions.

3056

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3057

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3062

# https://www.googleapis.com/auth/calendar.read

3063

},

3064

"requirements": [ # Requirements for additional authentication providers.

3065

{ # User-defined authentication requirements, including support for

3066

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3067

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3072

"audiences": "A String", # The list of JWT

3073

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3074

# that are allowed to access. A JWT containing any of these audiences will

3075

# be accepted. When this setting is absent, only JWTs with audience

3076

# "https://Service_name/API_name"

3077

# will be accepted. For example, if no audiences are in the setting,

3078

# LibraryService API will only accept JWTs with the following audience

3079

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3084

# bookstore_web.apps.googleusercontent.com

3085

},

3086

],

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

3087

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3088

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3089

#

3090

# For requests without credentials, if the service control environment is

3091

# specified, each incoming request **must** be associated with a service

3092

# consumer. This can be done by passing an API key that belongs to a consumer

3093

# project.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

3094

"selector": "A String", # Selects the methods to which this rule applies.

3095

#

3096

# Refer to selector for syntax details.

3097

},

3098

],

3099

"providers": [ # Defines a set of authentication providers that a service supports.

3100

{ # Configuration for an anthentication provider, including support for

3101

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3102

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3103

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3104

# Optional if the key set document:

3105

# - can be retrieved from

3106

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3107

# of the issuer.

3108

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3109

#

3110

# Example: https://www.googleapis.com/oauth2/v1/certs

3111

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3112

# `AuthRequirement.provider_id`.

3113

#

3114

# Example: "bookstore_auth".

3115

"issuer": "A String", # Identifies the principal that issued the JWT. See

3116

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3117

# Usually a URL or an email address.

3118

#

3119

# Example: https://securetoken.google.com

3120

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3125

"rules": [ # A list of usage rules that apply to individual API methods.

3126

#

3127

# **NOTE:** All service configuration rules follow "last one wins" order.

3128

{ # Usage configuration rules for the service.

3129

#

3130

# NOTE: Under development.

3131

#

3132

#

3133

# Use this rule to configure unregistered calls for the service. Unregistered

3134

# calls are calls that do not contain consumer project identity.

3135

# (Example: calls that do not contain an API key).

3136

# By default, API methods do not allow unregistered calls, and each method call

3137

# must be identified by a consumer project identity. Use this rule to

3138

# allow/disallow unregistered calls.

3139

#

3140

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3146

#

3147

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3152

# allow_unregistered_calls: true

3153

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3154

# methods in all APIs.

3155

#

3156

# Refer to selector for syntax details.

3157

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3158

},

3159

],

3160

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3161

# service. Each requirement is of the form <service.name>/<requirement-id>;

3162

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3167

# influence interpretation of the configuration, for example, to

3168

# determine defaults. This is documented together with applicable

3169

# options. The current default for the config version itself is `3`.

3170

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3171

# Members of this project can manage the service configuration,

3172

# manage consumption of the service, etc.

3173

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3174

# HttpRule, each specifying the mapping of an RPC method

3175

# to one or more HTTP REST API methods.

3176

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3177

#

3178

# **NOTE:** All service configuration rules follow "last one wins" order.

3179

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3180

# REST APIs. The mapping determines what portions of the request

3181

# message are populated from the path, query parameters, or body of

3182

# the HTTP request. The mapping is typically specified as an

3183

# `google.api.http` annotation, see "google/api/annotations.proto"

3184

# for details.

3185

#

3186

# The mapping consists of a field specifying the path template and

3187

# method kind. The path template can refer to fields in the request

3188

# message, as in the example below which describes a REST GET

3189

# operation on a resource collection of messages:

3190

#

3191

# ```proto

3192

# service Messaging {

3193

# rpc GetMessage(GetMessageRequest) returns (Message) {

3194

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3195

# }

3196

# }

3197

# message GetMessageRequest {

3198

# message SubMessage {

3199

# string subfield = 1;

3200

# }

3201

# string message_id = 1; // mapped to the URL

3202

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3203

# }

3204

# message Message {

3205

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

3210

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3215

#

3216

# In general, not only fields but also field paths can be referenced

3217

# from a path pattern. Fields mapped to the path pattern cannot be

3218

# repeated and must have a primitive (non-message) type.

3219

#

3220

# Any fields in the request message which are not bound by the path

3221

# pattern automatically become (optional) HTTP query

3222

# parameters. Assume the following definition of the request message:

3223

#

3224

# ```proto

3225

# message GetMessageRequest {

3226

# message SubMessage {

3227

# string subfield = 1;

3228

# }

3229

# string message_id = 1; // mapped to the URL

3230

# int64 revision = 2; // becomes a parameter

3231

# 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"))`

3240

#

3241

# Note that fields which are mapped to HTTP parameters must have a

3242

# primitive type or a repeated primitive type. Message types are not

3243

# allowed. In the case of a repeated type, the parameter can be

3244

# repeated in the URL, as in `...?param=A&param=B`.

3245

#

3246

# For HTTP method kinds which allow a request body, the `body` field

3247

# specifies the mapping. Consider a REST update method on the

3248

# message resource collection:

3249

#

3250

# ```proto

3251

# service Messaging {

3252

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3253

# option (google.api.http) = {

3254

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3260

# string message_id = 1; // mapped to the URL

3261

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

3266

# representation of the JSON in the request body is determined by

3267

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3272

#

3273

# The special name `*` can be used in the body mapping to define that

3274

# every field not bound by the path template should be mapped to the

3275

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

3280

# rpc UpdateMessage(Message) returns (Message) {

3281

# option (google.api.http) = {

3282

# 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!")`

3298

#

3299

# Note that when using `*` in the body mapping, it is not possible to

3300

# have HTTP parameters, as all fields not bound by the path end in

3301

# the body. This makes this option more rarely used in practice of

3302

# defining REST APIs. The common usage of `*` is in custom methods

3303

# which don't use the URL at all for transferring data.

3304

#

3305

# It is possible to define multiple HTTP methods for one RPC by using

3306

# the `additional_bindings` option. Example:

3307

#

3308

# ```proto

3309

# service Messaging {

3310

# rpc GetMessage(GetMessageRequest) returns (Message) {

3311

# option (google.api.http) = {

3312

# get: "/v1/messages/{message_id}"

3313

# additional_bindings {

3314

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

3320

# string message_id = 1;

3321

# 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")`

3331

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

3332

#

3333

# # Rules for HTTP mapping

3334

#

3335

# The rules for mapping HTTP path, query parameters, and body fields

3336

# to the request message are as follows:

3337

#

3338

# 1. The `body` field specifies either `*` or a field path, or is

3339

# omitted. If omitted, it assumes there is no HTTP body.

3340

# 2. Leaf fields (recursive expansion of nested messages in the

3341

# request) can be classified into three types:

3342

# (a) Matched in the URL template.

3343

# (b) Covered by body (if body is `*`, everything except (a) fields;

3344

# else everything under the body field)

3345

# (c) All other fields.

3346

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

3347

# 4. Any body sent with an HTTP request can contain only (b) fields.

3348

#

3349

# The syntax of the path template is as follows:

3350

#

3351

# Template = "/" Segments [ Verb ] ;

3352

# Segments = Segment { "/" Segment } ;

3353

# Segment = "*" | "**" | LITERAL | Variable ;

3354

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3355

# FieldPath = IDENT { "." IDENT } ;

3356

# Verb = ":" LITERAL ;

3357

#

3358

# The syntax `*` matches a single path segment. It follows the semantics of

3359

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3360

# Expansion.

3361

#

3362

# The syntax `**` matches zero or more path segments. It follows the semantics

3363

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

3364

# Expansion.

3365

#

3366

# The syntax `LITERAL` matches literal text in the URL path.

3367

#

3368

# The syntax `Variable` matches the entire path as specified by its template;

3369

# this nested template must not contain further variables. If a variable

3370

# matches a single path segment, its template may be omitted, e.g. `{var}`

3371

# is equivalent to `{var=*}`.

3372

#

3373

# NOTE: the field paths in variables and in the `body` must not refer to

3374

# repeated fields or map fields.

3375

#

3376

# Use CustomHttpPattern to specify any HTTP method that is not included in the

3377

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

3378

# a given URL path rule. The wild-card rule is useful for services that provide

3379

# content to Web (HTML) clients.

3380

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

3381

# `*` for mapping all fields not captured by the path pattern to the HTTP

3382

# body. NOTE: the referred field must not be a repeated field and must be

3383

# present at the top-level of response message type.

3384

"get": "A String", # Used for listing and getting information about resources.

3385

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3386

# [][google.bytestream.RestByteStream] as an API to your

3387

# configuration.

3388

# [][google.bytestream.RestByteStream] as an API to your

3389

# configuration.

3390

"enabled": True or False, # Whether download is enabled.

3391

},

3392

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3393

# not contain an `additional_bindings` field themselves (that is,

3394

# the nesting may only be one level deep).

3395

# Object with schema name: HttpRule

3396

],

3397

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3398

# [][google.bytestream.RestByteStream] as an API to your

3399

# configuration.

3400

# [][google.bytestream.RestByteStream] as an API to your

3401

# configuration.

3402

"enabled": True or False, # Whether upload is enabled.

3403

},

3404

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

3405

"path": "A String", # The path matched by this custom verb.

3406

"kind": "A String", # The name of this custom HTTP verb.

3407

},

3408

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

3409

# response. Other response fields are ignored. This field is optional. When

3410

# not set, the response message will be used as HTTP body of response.

3411

# NOTE: the referred field must be not a repeated field and must be present

3412

# at the top-level of response message type.

3413

"put": "A String", # Used for updating a resource.

3414

"patch": "A String", # Used for updating a resource.

3415

"post": "A String", # Used for creating a resource.

3416

"selector": "A String", # Selects methods to which this rule applies.

3417

#

3418

# Refer to selector for syntax details.

3419

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3424

# of the google.protobuf.Api needs to be provided by the configuration

3425

# author, as the remaining fields will be derived from the IDL during the

3426

# normalization process. It is an error to specify an API interface here

3427

# which cannot be resolved against the associated IDL files.

3428

{ # Api is a light-weight descriptor for a protocol buffer service.

3429

"methods": [ # The methods of this api, in unspecified order.

3430

{ # Method represents a method of an api.

3431

"name": "A String", # The simple name of this method.

3432

"requestStreaming": True or False, # If true, the request is streamed.

3433

"responseTypeUrl": "A String", # The URL of the output message type.

3434

"requestTypeUrl": "A String", # A URL of the input message type.

3435

"responseStreaming": True or False, # If true, the response is streamed.

3436

"syntax": "A String", # The source syntax of this method.

3437

"options": [ # Any metadata attached to the method.

3438

{ # A protocol buffer option, which can be attached to a message, field,

3439

# enumeration, etc.

3440

"name": "A String", # The option's name. For example, `"java_package"`.

3441

"value": { # The option's value. For example, `"com.google.protobuf"`.

3442

"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

3449

# message.

3450

# protobuf element, like the file in which it is defined.

3451

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3452

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3453

},

3454

"mixins": [ # Included APIs. See Mixin.

3455

{ # Declares an API to be included in this API. The including API must

3456

# redeclare all the methods from the included API, but documentation

3457

# and options are inherited as follows:

3458

#

3459

# - If after comment and whitespace stripping, the documentation

3460

# string of the redeclared method is empty, it will be inherited

3461

# from the original method.

3462

#

3463

# - Each annotation belonging to the service config (http,

3464

# visibility) which is not set in the redeclared method will be

3465

# inherited.

3466

#

3467

# - If an http annotation is inherited, the path pattern will be

3468

# modified as follows. Any version prefix will be replaced by the

3469

# version of the including API plus the root path if specified.

3470

#

3471

# Example of a simple mixin:

3472

#

3473

# package google.acl.v1;

3474

# service AccessControl {

3475

# // Get the underlying ACL object.

3476

# rpc GetAcl(GetAclRequest) returns (Acl) {

3477

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3482

# service Storage {

3483

# // rpc GetAcl(GetAclRequest) returns (Acl);

3484

#

3485

# // Get a data record.

3486

# rpc GetData(GetDataRequest) returns (Data) {

3487

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3492

#

3493

# apis:

3494

# - name: google.storage.v2.Storage

3495

# mixins:

3496

# - name: google.acl.v1.AccessControl

3497

#

3498

# The mixin construct implies that all methods in `AccessControl` are

3499

# also declared with same name and request/response types in

3500

# `Storage`. A documentation generator or annotation processor will

3501

# see the effective `Storage.GetAcl` method after inherting

3502

# documentation and annotations as follows:

3503

#

3504

# service Storage {

3505

# // Get the underlying ACL object.

3506

# rpc GetAcl(GetAclRequest) returns (Acl) {

3507

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3513

#

3514

# If the `root` field in the mixin is specified, it should be a

3515

# relative path under which inherited HTTP paths are placed. Example:

3516

#

3517

# apis:

3518

# - name: google.storage.v2.Storage

3519

# mixins:

3520

# - name: google.acl.v1.AccessControl

3521

# root: acls

3522

#

3523

# This implies the following inherited HTTP annotation:

3524

#

3525

# service Storage {

3526

# // Get the underlying ACL object.

3527

# rpc GetAcl(GetAclRequest) returns (Acl) {

3528

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3533

# are rooted.

3534

"name": "A String", # The fully qualified name of the API which is included.

3535

},

3536

],

3537

"syntax": "A String", # The source syntax of the service.

3538

"version": "A String", # A version string for this api. If specified, must have the form

3539

# `major-version.minor-version`, as in `1.10`. If the minor version

3540

# is omitted, it defaults to zero. If the entire version field is

3541

# empty, the major version is derived from the package name, as

3542

# outlined below. If the field is not empty, the version in the

3543

# package name will be verified to be consistent with what is

3544

# provided here.

3545

#

3546

# The versioning schema uses [semantic

3547

# versioning](http://semver.org) where the major version number

3548

# indicates a breaking change and the minor version an additive,

3549

# non-breaking change. Both version numbers are signals to users

3550

# what to expect from different versions, and should be carefully

3551

# chosen based on the product plan.

3552

#

3553

# The major version is also reflected in the package name of the

3554

# API, which must end in `v<major-version>`, as in

3555

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3556

# be omitted. Zero major versions must only be used for

3557

# experimental, none-GA apis.

3558

"options": [ # Any metadata attached to the API.

3559

{ # A protocol buffer option, which can be attached to a message, field,

3560

# enumeration, etc.

3561

"name": "A String", # The option's name. For example, `"java_package"`.

3562

"value": { # The option's value. For example, `"com.google.protobuf"`.

3563

"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

3568

# followed by the api's simple name.

3569

},

3570

],

3571

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3572

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3580

# - google.foo.v1.AnotherError

3581

"rules": [ # The list of custom error rules that apply to individual API messages.

3582

#

3583

# **NOTE:** All service configuration rules follow "last one wins" order.

3584

{ # A custom error rule.

3585

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3586

# objects of this type will be filtered when they appear in error payload.

3587

"selector": "A String", # Selects messages to which this rule applies.

3588

#

3589

# Refer to selector for syntax details.

3590

},

3591

],

3592

"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.

3597

# elements. Restrictions are specified using visibility labels

3598

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3599

#

3600

# Users and projects can have access to more than one visibility label. The

3601

# effective visibility for multiple labels is the union of each label's

3602

# elements, plus any unrestricted elements.

3603

#

3604

# If an element and its parents have no restrictions, visibility is

3605

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3612

# restriction: TRUSTED_TESTER

3613

# - selector: google.calendar.Calendar.Delegate

3614

# restriction: GOOGLE_INTERNAL

3615

#

3616

# Here, all methods are publicly visible except for the restricted methods

3617

# EnhancedSearch and Delegate.

3618

"rules": [ # A list of visibility rules that apply to individual API elements.

3619

#

3620

# **NOTE:** All service configuration rules follow "last one wins" order.

3621

{ # A visibility rule provides visibility configuration for an individual API

3622

# element.

3623

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

3624

# visibility to the element.

3625

#

3626

# If a rule has multiple labels, removing one of the labels but not all of

3627

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3634

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

3635

#

3636

# Removing GOOGLE_INTERNAL from this restriction will break clients that

3637

# rely on this method and only had access to it through GOOGLE_INTERNAL.

3638

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

3639

#

3640

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

3645

{ # Defines a metric type and its schema.

3646

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3647

# Use sentence case without an ending period, for example "Request count".

3648

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3649

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

3650

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

3651

"labels": [ # The set of labels that can be used to describe a specific instance of this

3652

# metric type. For example, the

3653

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

3654

# has a label, `loadbalanced`, that specifies whether the traffic was

3655

# received through a load balanced IP address.

3656

{ # A description of a label.

3657

"valueType": "A String", # The type of data that can be assigned to the label.

3658

"description": "A String", # A human-readable description for the label.

3659

"key": "A String", # The label key.

3660

},

3661

],

3662

"type": "A String", # The metric type including a DNS name prefix, for example

3663

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

3664

# should use a natural hierarchical grouping such as the following:

3665

#

3666

# compute.googleapis.com/instance/cpu/utilization

3667

# compute.googleapis.com/instance/disk/read_ops_count

3668

# compute.googleapis.com/instance/network/received_bytes_count

3669

#

3670

# Note that if the metric type changes, the monitoring data will be

3671

# discontinued, and anything depends on it will break, such as monitoring

3672

# dashboards, alerting rules and quota limits. Therefore, once a metric has

3673

# been published, its type should be immutable.

3674

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

3675

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

3676

# supported units are a subset of [The Unified Code for Units of

3677

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3678

#

3679

# **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)

3694

# * `P` peta (10**15)

3695

# * `E` exa (10**18)

3696

# * `Z` zetta (10**21)

3697

# * `Y` yotta (10**24)

3698

# * `m` milli (10**-3)

3699

# * `u` micro (10**-6)

3700

# * `n` nano (10**-9)

3701

# * `p` pico (10**-12)

3702

# * `f` femto (10**-15)

3703

# * `a` atto (10**-18)

3704

# * `z` zepto (10**-21)

3705

# * `y` yocto (10**-24)

3706

# * `Ki` kibi (2**10)

3707

# * `Mi` mebi (2**20)

3708

# * `Gi` gibi (2**30)

3709

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

3714

#

3715

# The grammar also includes these connectors:

3716

#

3717

# * `/` division (as an infix operator, e.g. `1/s`).

3718

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

3719

#

3720

# The grammar for a unit is as follows:

3721

#

3722

# Expression = Component { "." Component } { "/" Component } ;

3723

#

3724

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

3734

# equivalent to `1` if it is used alone. For examples,

3735

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

3736

# * `NAME` is a sequence of non-blank printable ASCII characters not

3737

# containing '{' or '}'.

3738

"name": "A String", # Resource name. The format of the name may vary between different

3739

# implementations. For examples:

3740

#

3741

# projects/{project_id}/metricDescriptors/{type=**}

3742

# metricDescriptors/{type=**}

3743

},

3744

],

3745

"enums": [ # A list of all enum types included in this API service. Enums

3746

# referenced directly or indirectly by the `apis` are automatically

3747

# included. Enums which are not referenced but shall be included

3748

# should be listed here by name. Example:

3749

#

3750

# enums:

3751

# - name: google.someapi.v1.SomeEnum

3752

{ # Enum type definition.

3753

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3754

# protobuf element, like the file in which it is defined.

3755

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3756

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3757

},

3758

"enumvalue": [ # Enum value definitions.

3759

{ # Enum value definition.

3760

"number": 42, # Enum value number.

3761

"options": [ # Protocol buffer options.

3762

{ # A protocol buffer option, which can be attached to a message, field,

3763

# enumeration, etc.

3764

"name": "A String", # The option's name. For example, `"java_package"`.

3765

"value": { # The option's value. For example, `"com.google.protobuf"`.

3766

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

3771

},

3772

],

3773

"options": [ # Protocol buffer options.

3774

{ # A protocol buffer option, which can be attached to a message, field,

3775

# enumeration, etc.

3776

"name": "A String", # The option's name. For example, `"java_package"`.

3777

"value": { # The option's value. For example, `"com.google.protobuf"`.

3778

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

3783

"syntax": "A String", # The source syntax.

3784

},

3785

],

3786

"types": [ # A list of all proto message types included in this API service.

3787

# Types referenced directly or indirectly by the `apis` are

3788

# automatically included. Messages which are not referenced but

3789

# shall be included, such as types used by the `google.protobuf.Any` type,

3790

# should be listed here by name. Example:

3791

#

3792

# types:

3793

# - name: google.protobuf.Int32

3794

{ # A protocol buffer message type.

3795

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3796

"A String",

3797

],

3798

"name": "A String", # The fully qualified message name.

3799

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3800

# protobuf element, like the file in which it is defined.

3801

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3802

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3803

},

3804

"syntax": "A String", # The source syntax.

3805

"fields": [ # The list of fields.

3806

{ # A single field of a message type.

3807

"kind": "A String", # The field type.

3808

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3809

# types. The first type has index 1; zero means the type is not in the list.

3810

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3811

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3812

"name": "A String", # The field name.

3813

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3814

"jsonName": "A String", # The field JSON name.

3815

"number": 42, # The field number.

3816

"cardinality": "A String", # The field cardinality.

3817

"options": [ # The protocol buffer options.

3818

{ # A protocol buffer option, which can be attached to a message, field,

3819

# enumeration, etc.

3820

"name": "A String", # The option's name. For example, `"java_package"`.

3821

"value": { # The option's value. For example, `"com.google.protobuf"`.

3822

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3827

},

3828

],

3829

"options": [ # The protocol buffer options.

3830

{ # A protocol buffer option, which can be attached to a message, field,

3831

# enumeration, etc.

3832

"name": "A String", # The option's name. For example, `"java_package"`.

3833

"value": { # The option's value. For example, `"com.google.protobuf"`.

3834

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

3841

#

3842

# The following example shows how to configure logs to be sent to the

3843

# producer and consumer projects. In the example,

3844

# the `library.googleapis.com/activity_history` log is

3845

# sent to both the producer and consumer projects, whereas

3846

# the `library.googleapis.com/purchase_history` log is only sent to the

3847

# producer project:

3848

#

3849

# monitored_resources:

3850

# - type: library.googleapis.com/branch

3851

# labels:

3852

# - key: /city

3853

# description: The city where the library branch is located in.

3854

# - key: /name

3855

# description: The name of the branch.

3856

# logs:

3857

# - name: library.googleapis.com/activity_history

3858

# labels:

3859

# - key: /customer_id

3860

# - name: library.googleapis.com/purchase_history

3861

# logging:

3862

# producer_destinations:

3863

# - monitored_resource: library.googleapis.com/branch

3864

# logs:

3865

# - library.googleapis.com/activity_history

3866

# - library.googleapis.com/purchase_history

3867

# consumer_destinations:

3868

# - monitored_resource: library.googleapis.com/branch

3869

# logs:

3870

# - library.googleapis.com/activity_history

3871

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3872

# There can be multiple producer destinations, each one must have a

3873

# different monitored resource type. A log can be used in at most

3874

# one producer destination.

3875

{ # Configuration of a specific logging destination (the producer project

3876

# or the consumer project).

3877

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3878

# Service.monitored_resources section.

3879

"logs": [ # Names of the logs to be sent to this destination. Each name must

3880

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

3886

# There can be multiple consumer destinations, each one must have a

3887

# different monitored resource type. A log can be used in at most

3888

# one consumer destination.

3889

{ # Configuration of a specific logging destination (the producer project

3890

# or the consumer project).

3891

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3892

# Service.monitored_resources section.

3893

"logs": [ # Names of the logs to be sent to this destination. Each name must

3894

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

3901

# e.g. `calendar.googleapis.com`.

3902

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

3903

#

3904

# Example:

3905

# <pre><code>documentation:

3906

# summary: >

3907

# The Google Calendar API gives access

3908

# to most calendar features.

3909

# pages:

3910

# - name: Overview

3911

# content: (== include google/foo/overview.md ==)

3912

# - name: Tutorial

3913

# content: (== include google/foo/tutorial.md ==)

3914

# subpages;

3915

# - name: Java

3916

# content: (== include google/foo/tutorial_java.md ==)

3917

# rules:

3918

# - selector: google.calendar.Calendar.Get

3919

# description: >

3920

# ...

3921

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3926

# standard markdown features, definition lists, tables and fenced

3927

# code blocks are supported. Section headers can be provided and are

3928

# interpreted relative to the section nesting of the context where

3929

# a documentation fragment is embedded.

3930

#

3931

# Documentation from the IDL is merged with documentation defined

3932

# via the config at normalization time, where documentation provided

3933

# by config rules overrides IDL provided.

3934

#

3935

# A number of constructs specific to the API platform are supported

3936

# in documentation text.

3937

#

3938

# In order to reference a proto element, the following

3939

# notation can be used:

3940

# <pre><code>[fully.qualified.proto.name][]</code></pre>

3941

# To override the display text used for the link, this can be used:

3942

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

3943

# Text can be excluded from doc using the following notation:

3944

# <pre><code>(-- internal comment --)</code></pre>

3945

# Comments can be made conditional using a visibility label. The below

3946

# text will be only rendered if the `BETA` label is available:

3947

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

3948

# A few directives are available in documentation. Note that

3949

# directives must appear on a single line to be properly

3950

# identified. The `include` directive includes a markdown file from

3951

# an external source:

3952

# <pre><code>(== include path/to/file ==)</code></pre>

3953

# The `resource_for` directive marks a message to be the resource of

3954

# a collection in REST view. If it is not specified, tools attempt

3955

# to infer the resource from the operations in a collection:

3956

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

3957

# The directive `suppress_warning` does not directly affect documentation

3958

# and is documented together with service config validation.

3959

"rules": [ # A list of documentation rules that apply to individual API elements.

3960

#

3961

# **NOTE:** All service configuration rules follow "last one wins" order.

3962

{ # A documentation rule provides information about individual API elements.

3963

"description": "A String", # Description of the selected API(s).

3964

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

3965

# element is marked as `deprecated`.

3966

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3967

# qualified name of the element which may end in "*", indicating a wildcard.

3968

# Wildcards are only allowed at the end and for a whole component of the

3969

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

3970

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

3975

# <pre><code>documentation:

3976

# summary: ...

3977

# overview: (== include overview.md ==)

3978

# </code></pre>

3979

# This is a shortcut for the following declaration (using pages style):

3980

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

3985

# </code></pre>

3986

# Note: you cannot specify both `overview` field and `pages` field.

3987

"summary": "A String", # A short summary of what the service does. Can only be provided by

3988

# plain text.

3989

"pages": [ # The top level pages for the documentation set.

3990

{ # Represents a documentation page. A page can contain subpages to represent

3991

# nested documentation set structure.

3992

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

3993

# to include content from a Markdown file.

3994

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3995

# honored in the generated docset.

3996

# Object with schema name: Page

3997

],

3998

"name": "A String", # The name of the page. It will be used as an identity of the page to

3999

# generate URI of the page, text of the link to this page in navigation,

4000

# etc. The full page name (start from the root page name to this page

4001

# concatenated with `.`) can be used as reference to the page in your

4002

# documentation. For example:

4003

# <pre><code>pages:

4004

# - name: Tutorial

4005

# content: (== include tutorial.md ==)

4006

# subpages:

4007

# - name: Java

4008

# content: (== include tutorial_java.md ==)

4009

# </code></pre>

4010

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

4015

},

4016

"systemTypes": [ # A list of all proto message types included in this API service.

4017

# It serves similar purpose as [google.api.Service.types], except that

4018

# these types are not needed by user-defined APIs. Therefore, they will not

4019

# show up in the generated discovery doc. This field should only be used

4020

# to define system APIs in ESF.

4021

{ # A protocol buffer message type.

4022

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4023

"A String",

4024

],

4025

"name": "A String", # The fully qualified message name.

4026

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4027

# protobuf element, like the file in which it is defined.

4028

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4029

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4030

},

4031

"syntax": "A String", # The source syntax.

4032

"fields": [ # The list of fields.

4033

{ # A single field of a message type.

4034

"kind": "A String", # The field type.

4035

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4036

# types. The first type has index 1; zero means the type is not in the list.

4037

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4038

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4039

"name": "A String", # The field name.

4040

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4041

"jsonName": "A String", # The field JSON name.

4042

"number": 42, # The field number.

4043

"cardinality": "A String", # The field cardinality.

4044

"options": [ # The protocol buffer options.

4045

{ # A protocol buffer option, which can be attached to a message, field,

4046

# enumeration, etc.

4047

"name": "A String", # The option's name. For example, `"java_package"`.

4048

"value": { # The option's value. For example, `"com.google.protobuf"`.

4049

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4054

},

4055

],

4056

"options": [ # The protocol buffer options.

4057

{ # A protocol buffer option, which can be attached to a message, field,

4058

# enumeration, etc.

4059

"name": "A String", # The option's name. For example, `"java_package"`.

4060

"value": { # The option's value. For example, `"com.google.protobuf"`.

4061

"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

4076

# - google.rpc.context.OriginContext

4077

#

4078

# The above specifies that all methods in the API request

4079

# `google.rpc.context.ProjectContext` and

4080

# `google.rpc.context.OriginContext`.

4081

#

4082

# Available context types are defined in package

4083

# `google.rpc.context`.

4084

"rules": [ # A list of RPC context rules that apply to individual API methods.

4085

#

4086

# **NOTE:** All service configuration rules follow "last one wins" order.

4087

{ # A context rule provides information about the context for an individual API

4088

# element.

4089

"provided": [ # A list of full type names of provided contexts.

4090

"A String",

4091

],

4092

"requested": [ # A list of full type names of requested contexts.

4093

"A String",

4094

],

4095

"selector": "A String", # Selects the methods to which this rule applies.

4096

#

4097

# Refer to selector for syntax details.

},

],

},

}</pre>

</div>

<code class="details" id="list">list(serviceName=None, pageSize=None, pageToken=None, x__xgafv=None)</code>

4106

<pre>Lists the history of the service configuration for a managed service,

4107

from the newest to the oldest.

4108

4109

Args:

4110

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4111

for naming requirements. For example: `example.googleapis.com`. (required)

4112

pageSize: integer, The max number of items to include in the response list.

4113

pageToken: string, The token of the page to retrieve.

4114

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4121

4122

{ # Response message for ListServiceConfigs method.

4123

"nextPageToken": "A String", # The token of the next page of results.

4124

"serviceConfigs": [ # The list of service configuration resources.

4125

{ # `Service` is the root object of the configuration schema. It

4126

# describes basic information like the name of the service and the

4127

# exposed API interfaces, and delegates other aspects to configuration

# sub-sections.

#

# Example:

#

# type: google.api.Service

4133

# config_version: 1

4134

# name: calendar.googleapis.com

4135

# title: Google Calendar API

4136

# apis:

4137

# - name: google.calendar.Calendar

# backend:

# rules:

# - selector: "*"

# address: calendar.example.com

4142

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4143

# service controller handles features like abuse, quota, billing, logging,

4144

# monitoring, etc.

4145

"environment": "A String", # The service control environment to use. If empty, no control plane

4146

# feature (like quota and billing) will be enabled.

4147

},

4148

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4149

# by the Service.monitoring and Service.logging configurations.

4150

{ # An object that describes the schema of a MonitoredResource object using a

4151

# type name and a set of labels. For example, the monitored resource

4152

# descriptor for Google Compute Engine VM instances has a type of

4153

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4154

# `"zone"` to identify particular VM instances.

4155

#

4156

# Different APIs can support different monitored resource types. APIs generally

4157

# provide a `list` method that returns the monitored resource descriptors used

4158

# by the API.

4159

"type": "A String", # Required. The monitored resource type. For example, the type

4160

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4161

# The maximum length of this value is 256 characters.

4162

"labels": [ # Required. A set of labels used to describe instances of this monitored

4163

# resource type. For example, an individual Google Cloud SQL database is

4164

# identified by values for the labels `"database_id"` and `"zone"`.

4165

{ # A description of a label.

4166

"valueType": "A String", # The type of data that can be assigned to the label.

4167

"description": "A String", # A human-readable description for the label.

4168

"key": "A String", # The label key.

4169

},

4170

],

4171

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

4172

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

4173

# without any article or other determiners. For example,

4174

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

4175

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4176

# be used in documentation.

4177

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4178

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4179

# {type} is the value of the `type` field in this object and

4180

# {project_id} is a project ID that provides API-specific context for

4181

# accessing the type. APIs that do not use project information can use the

4182

# resource name format `"monitoredResourceDescriptors/{type}"`.

4183

},

4184

],

4185

"logs": [ # Defines the logs used by this service.

4186

{ # A description of a log type. Example in YAML format:

4187

#

4188

# - name: library.googleapis.com/activity_history

4189

# description: The history of borrowing and returning library items.

4190

# display_name: Activity

4191

# labels:

4192

# - key: /customer_id

4193

# description: Identifier of a library customer

4194

"labels": [ # The set of labels that are available to describe a specific log entry.

4195

# Runtime requests that contain labels not specified here are

4196

# considered invalid.

4197

{ # A description of a label.

4198

"valueType": "A String", # The type of data that can be assigned to the label.

4199

"description": "A String", # A human-readable description for the label.

4200

"key": "A String", # The label key.

4201

},

4202

],

4203

"displayName": "A String", # The human-readable name for this log. This information appears on

4204

# the user interface and should be concise.

4205

"description": "A String", # A human-readable description of this log. This information appears in

4206

# the documentation and can contain details.

4207

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4208

# include the following characters: upper- and lower-case alphanumeric

4209

# characters [A-Za-z0-9], and punctuation characters including

4210

# slash, underscore, hyphen, period [/_-.].

4211

},

4212

],

4213

"systemParameters": { # ### System parameter configuration # Configuration for system parameters.

4214

#

4215

# A system parameter is a special kind of parameter defined by the API

4216

# system, not by an individual API. It is typically mapped to an HTTP header

4217

# and/or a URL query parameter. This configuration specifies which methods

4218

# change the names of the system parameters.

4219

"rules": [ # Define system parameters.

4220

#

4221

# The parameters defined here will override the default parameters

4222

# implemented by the system. If this field is missing from the service

4223

# config, default system parameters will be used. Default system parameters

4224

# and names is implementation-dependent.

4225

#

4226

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4234

# - name: alt

4235

# http_header: Response-Content-Type

4236

#

4237

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4242

# parameters:

4243

# - name: api_key

4244

# http_header: Api-Key1

4245

# - name: api_key

4246

# http_header: Api-Key2

4247

#

4248

# **NOTE:** All service configuration rules follow "last one wins" order.

4249

{ # Define a system parameter rule mapping system parameter definitions to

4250

# methods.

4251

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4252

# For a given method call, only one of them should be used. If multiple

4253

# names are used the behavior is implementation-dependent.

4254

# If none of the specified names are present the behavior is

4255

# parameter-dependent.

4256

{ # Define a parameter's name and location. The parameter may be passed as either

4257

# an HTTP header or a URL query parameter, and if both are passed the behavior

4258

# is implementation-dependent.

4259

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4260

# sensitive.

4261

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

4262

# and etc. It is case sensitive.

4263

"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

4268

# methods in all APIs.

4269

#

4270

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4275

"rules": [ # A list of API backend rules that apply to individual API methods.

4276

#

4277

# **NOTE:** All service configuration rules follow "last one wins" order.

4278

{ # A backend rule provides configuration for an individual API element.

4279

"selector": "A String", # Selects the methods to which this rule applies.

4280

#

4281

# Refer to selector for syntax details.

4282

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4283

# default depends on the deployment context.

4284

"address": "A String", # The address of the API backend.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration of the service.

4289

#

4290

# The example below shows how to configure monitored resources and metrics

4291

# for monitoring. In the example, a monitored resource and two metrics are

4292

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4293

# to both producer and consumer projects, whereas the

4294

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4295

# consumer project.

4296

#

4297

# monitored_resources:

4298

# - type: library.googleapis.com/branch

4299

# labels:

4300

# - key: /city

4301

# description: The city where the library branch is located in.

4302

# - key: /name

4303

# description: The name of the branch.

4304

# metrics:

4305

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4310

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4315

# monitoring:

4316

# producer_destinations:

4317

# - monitored_resource: library.googleapis.com/branch

4318

# metrics:

4319

# - library.googleapis.com/book/returned_count

4320

# consumer_destinations:

4321

# - monitored_resource: library.googleapis.com/branch

4322

# metrics:

4323

# - library.googleapis.com/book/returned_count

4324

# - library.googleapis.com/book/overdue_count

4325

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4326

# There can be multiple producer destinations, each one must have a

4327

# different monitored resource type. A metric can be used in at most

4328

# one producer destination.

4329

{ # Configuration of a specific monitoring destination (the producer project

4330

# or the consumer project).

4331

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4332

# Service.monitored_resources section.

4333

"metrics": [ # Names of the metrics to report to this monitoring destination.

4334

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4340

# There can be multiple consumer destinations, each one must have a

4341

# different monitored resource type. A metric can be used in at most

4342

# one consumer destination.

4343

{ # Configuration of a specific monitoring destination (the producer project

4344

# or the consumer project).

4345

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4346

# Service.monitored_resources section.

4347

"metrics": [ # Names of the metrics to report to this monitoring destination.

4348

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

4355

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4356

# by the client for tracking purpose. If empty, the server may choose to

4357

# generate one instead.

4358

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4359

#

4360

# Example for an API targeted for external use:

4361

#

4362

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

4368

#

4369

# - selector: google.calendar.Delegate

4370

# oauth:

4371

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

4372

"rules": [ # A list of authentication rules that apply to individual API methods.

4373

#

4374

# **NOTE:** All service configuration rules follow "last one wins" order.

4375

{ # Authentication rules for the service.

4376

#

4377

# By default, if a method has any authentication requirements, every request

4378

# must include a valid credential matching one of the requirements.

4379

# It's an error to include more than one kind of credential in a single

4380

# request.

4381

#

4382

# If a method doesn't have any auth requirements, request credentials will be

4383

# ignored.

4384

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4385

# there are scopes defined for "Read-only access to Google Calendar" and

4386

# "Access to Cloud Platform". Users can consent to a scope for an application,

4387

# giving it permission to access that data on their behalf.

4388

#

4389

# OAuth scope specifications should be fairly coarse grained; a user will need

4390

# to see and understand the text description of what your scope means.

4391

#

4392

# In most cases: use one or at most two OAuth scopes for an entire family of

4393

# products. If your product has multiple APIs, you should probably be sharing

4394

# the OAuth scope across all of those APIs.

4395

#

4396

# When you need finer grained OAuth consent screens: talk with your product

4397

# management about how developers will use them in practice.

4398

#

4399

# Please note that even though each of the canonical scopes is enough for a

4400

# request to be accepted and passed to the backend, a request can still fail

4401

# due to the backend requiring additional scopes or permissions.

4402

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4403

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4408

# https://www.googleapis.com/auth/calendar.read

4409

},

4410

"requirements": [ # Requirements for additional authentication providers.

4411

{ # User-defined authentication requirements, including support for

4412

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4413

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

4418

"audiences": "A String", # The list of JWT

4419

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4420

# that are allowed to access. A JWT containing any of these audiences will

4421

# be accepted. When this setting is absent, only JWTs with audience

4422

# "https://Service_name/API_name"

4423

# will be accepted. For example, if no audiences are in the setting,

4424

# LibraryService API will only accept JWTs with the following audience

4425

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4430

# bookstore_web.apps.googleusercontent.com

4431

},

4432

],

Jon Wayne Parrott

2512a0c

2016-08-29 10:21:22 -0700

[diff] [blame^]

4433

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

4434

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

4435

#

4436

# For requests without credentials, if the service control environment is

4437

# specified, each incoming request **must** be associated with a service

4438

# consumer. This can be done by passing an API key that belongs to a consumer

4439

# project.

Jon Wayne Parrott

7d5badb

2016-08-16 12:44:29 -0700

[diff] [blame]

4440

"selector": "A String", # Selects the methods to which this rule applies.

4441

#

4442

# Refer to selector for syntax details.

4443

},

4444

],

4445

"providers": [ # Defines a set of authentication providers that a service supports.

4446

{ # Configuration for an anthentication provider, including support for

4447

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4448

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4449

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4450

# Optional if the key set document:

4451

# - can be retrieved from

4452

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4453

# of the issuer.

4454

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4455

#

4456

# Example: https://www.googleapis.com/oauth2/v1/certs

4457

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4458

# `AuthRequirement.provider_id`.

4459

#

4460

# Example: "bookstore_auth".

4461

"issuer": "A String", # Identifies the principal that issued the JWT. See

4462

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4463

# Usually a URL or an email address.

4464

#

4465

# Example: https://securetoken.google.com

4466

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4471

"rules": [ # A list of usage rules that apply to individual API methods.

4472

#

4473

# **NOTE:** All service configuration rules follow "last one wins" order.

4474

{ # Usage configuration rules for the service.

4475

#

4476

# NOTE: Under development.

4477

#

4478

#

4479

# Use this rule to configure unregistered calls for the service. Unregistered

4480

# calls are calls that do not contain consumer project identity.

4481

# (Example: calls that do not contain an API key).

4482

# By default, API methods do not allow unregistered calls, and each method call

4483

# must be identified by a consumer project identity. Use this rule to

4484

# allow/disallow unregistered calls.

4485

#

4486

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4492

#

4493

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4498

# allow_unregistered_calls: true

4499

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4500

# methods in all APIs.

4501

#

4502

# Refer to selector for syntax details.

4503

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4504

},

4505

],

4506

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4507

# service. Each requirement is of the form <service.name>/<requirement-id>;

4508

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

4513

# influence interpretation of the configuration, for example, to

4514

# determine defaults. This is documented together with applicable

4515

# options. The current default for the config version itself is `3`.

4516

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

4517

# Members of this project can manage the service configuration,

4518

# manage consumption of the service, etc.

4519

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

4520

# HttpRule, each specifying the mapping of an RPC method

4521

# to one or more HTTP REST API methods.

4522

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4523

#

4524

# **NOTE:** All service configuration rules follow "last one wins" order.

4525

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

4526

# REST APIs. The mapping determines what portions of the request

4527

# message are populated from the path, query parameters, or body of

4528

# the HTTP request. The mapping is typically specified as an

4529

# `google.api.http` annotation, see "google/api/annotations.proto"

4530

# for details.

4531

#

4532

# The mapping consists of a field specifying the path template and

4533

# method kind. The path template can refer to fields in the request

4534

# message, as in the example below which describes a REST GET

4535

# operation on a resource collection of messages:

4536

#

4537

# ```proto

4538

# service Messaging {

4539

# rpc GetMessage(GetMessageRequest) returns (Message) {

4540

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4541

# }

4542

# }

4543

# message GetMessageRequest {

4544

# message SubMessage {

4545

# string subfield = 1;

4546

# }

4547

# string message_id = 1; // mapped to the URL

4548

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4549

# }

4550

# message Message {

4551

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

4556

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4561

#

4562

# In general, not only fields but also field paths can be referenced

4563

# from a path pattern. Fields mapped to the path pattern cannot be

4564

# repeated and must have a primitive (non-message) type.

4565

#

4566

# Any fields in the request message which are not bound by the path

4567

# pattern automatically become (optional) HTTP query

4568

# parameters. Assume the following definition of the request message:

4569

#

4570

# ```proto

4571

# message GetMessageRequest {

4572

# message SubMessage {

4573

# string subfield = 1;

4574

# }

4575

# string message_id = 1; // mapped to the URL

4576

# int64 revision = 2; // becomes a parameter

4577

# 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"))`

4586

#

4587

# Note that fields which are mapped to HTTP parameters must have a

4588

# primitive type or a repeated primitive type. Message types are not

4589

# allowed. In the case of a repeated type, the parameter can be

4590

# repeated in the URL, as in `...?param=A&param=B`.

4591

#

4592

# For HTTP method kinds which allow a request body, the `body` field

4593

# specifies the mapping. Consider a REST update method on the

4594

# message resource collection:

4595

#

4596

# ```proto

4597

# service Messaging {

4598

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4599

# option (google.api.http) = {

4600

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4606

# string message_id = 1; // mapped to the URL

4607

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

4612

# representation of the JSON in the request body is determined by

4613

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

4618

#

4619

# The special name `*` can be used in the body mapping to define that

4620

# every field not bound by the path template should be mapped to the

4621

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

4626

# rpc UpdateMessage(Message) returns (Message) {

4627

# option (google.api.http) = {

4628

# 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!")`

4644

#

4645

# Note that when using `*` in the body mapping, it is not possible to

4646

# have HTTP parameters, as all fields not bound by the path end in

4647

# the body. This makes this option more rarely used in practice of

4648

# defining REST APIs. The common usage of `*` is in custom methods

4649

# which don't use the URL at all for transferring data.

4650

#

4651

# It is possible to define multiple HTTP methods for one RPC by using

4652

# the `additional_bindings` option. Example:

4653

#

4654

# ```proto

4655

# service Messaging {

4656

# rpc GetMessage(GetMessageRequest) returns (Message) {

4657

# option (google.api.http) = {

4658

# get: "/v1/messages/{message_id}"

4659

# additional_bindings {

4660

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

4666

# string message_id = 1;

4667

# 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")`

4677

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

4678

#

4679

# # Rules for HTTP mapping

4680

#

4681

# The rules for mapping HTTP path, query parameters, and body fields

4682

# to the request message are as follows:

4683

#

4684

# 1. The `body` field specifies either `*` or a field path, or is

4685

# omitted. If omitted, it assumes there is no HTTP body.

4686

# 2. Leaf fields (recursive expansion of nested messages in the

4687

# request) can be classified into three types:

4688

# (a) Matched in the URL template.

4689

# (b) Covered by body (if body is `*`, everything except (a) fields;

4690

# else everything under the body field)

4691

# (c) All other fields.

4692

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

4693

# 4. Any body sent with an HTTP request can contain only (b) fields.

4694

#

4695

# The syntax of the path template is as follows:

4696

#

4697

# Template = "/" Segments [ Verb ] ;

4698

# Segments = Segment { "/" Segment } ;

4699

# Segment = "*" | "**" | LITERAL | Variable ;

4700

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4701

# FieldPath = IDENT { "." IDENT } ;

4702

# Verb = ":" LITERAL ;

4703

#

4704

# The syntax `*` matches a single path segment. It follows the semantics of

4705

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4706

# Expansion.

4707

#

4708

# The syntax `**` matches zero or more path segments. It follows the semantics

4709

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

4710

# Expansion.

4711

#

4712

# The syntax `LITERAL` matches literal text in the URL path.

4713

#

4714

# The syntax `Variable` matches the entire path as specified by its template;

4715

# this nested template must not contain further variables. If a variable

4716

# matches a single path segment, its template may be omitted, e.g. `{var}`

4717

# is equivalent to `{var=*}`.

4718

#

4719

# NOTE: the field paths in variables and in the `body` must not refer to

4720

# repeated fields or map fields.

4721

#

4722

# Use CustomHttpPattern to specify any HTTP method that is not included in the

4723

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

4724

# a given URL path rule. The wild-card rule is useful for services that provide

4725

# content to Web (HTML) clients.

4726

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

4727

# `*` for mapping all fields not captured by the path pattern to the HTTP

4728

# body. NOTE: the referred field must not be a repeated field and must be

4729

# present at the top-level of response message type.

4730

"get": "A String", # Used for listing and getting information about resources.

4731

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4732

# [][google.bytestream.RestByteStream] as an API to your

4733

# configuration.

4734

# [][google.bytestream.RestByteStream] as an API to your

4735

# configuration.

4736

"enabled": True or False, # Whether download is enabled.

4737

},

4738

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4739

# not contain an `additional_bindings` field themselves (that is,

4740

# the nesting may only be one level deep).

4741

# Object with schema name: HttpRule

4742

],

4743

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4744

# [][google.bytestream.RestByteStream] as an API to your

4745

# configuration.

4746

# [][google.bytestream.RestByteStream] as an API to your

4747

# configuration.

4748

"enabled": True or False, # Whether upload is enabled.

4749

},

4750

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

4751

"path": "A String", # The path matched by this custom verb.

4752

"kind": "A String", # The name of this custom HTTP verb.

4753

},

4754

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

4755

# response. Other response fields are ignored. This field is optional. When

4756

# not set, the response message will be used as HTTP body of response.

4757

# NOTE: the referred field must be not a repeated field and must be present

4758

# at the top-level of response message type.

4759

"put": "A String", # Used for updating a resource.

4760

"patch": "A String", # Used for updating a resource.

4761

"post": "A String", # Used for creating a resource.

4762

"selector": "A String", # Selects methods to which this rule applies.

4763

#

4764

# Refer to selector for syntax details.

4765

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4770

# of the google.protobuf.Api needs to be provided by the configuration

4771

# author, as the remaining fields will be derived from the IDL during the

4772

# normalization process. It is an error to specify an API interface here

4773

# which cannot be resolved against the associated IDL files.

4774

{ # Api is a light-weight descriptor for a protocol buffer service.

4775

"methods": [ # The methods of this api, in unspecified order.

4776

{ # Method represents a method of an api.

4777

"name": "A String", # The simple name of this method.

4778

"requestStreaming": True or False, # If true, the request is streamed.

4779

"responseTypeUrl": "A String", # The URL of the output message type.

4780

"requestTypeUrl": "A String", # A URL of the input message type.

4781

"responseStreaming": True or False, # If true, the response is streamed.

4782

"syntax": "A String", # The source syntax of this method.

4783

"options": [ # Any metadata attached to the method.

4784

{ # A protocol buffer option, which can be attached to a message, field,

4785

# enumeration, etc.

4786

"name": "A String", # The option's name. For example, `"java_package"`.

4787

"value": { # The option's value. For example, `"com.google.protobuf"`.

4788

"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

4795

# message.

4796

# protobuf element, like the file in which it is defined.

4797

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4798

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4799

},

4800

"mixins": [ # Included APIs. See Mixin.

4801

{ # Declares an API to be included in this API. The including API must

4802

# redeclare all the methods from the included API, but documentation

4803

# and options are inherited as follows:

4804

#

4805

# - If after comment and whitespace stripping, the documentation

4806

# string of the redeclared method is empty, it will be inherited

4807

# from the original method.

4808

#

4809

# - Each annotation belonging to the service config (http,

4810

# visibility) which is not set in the redeclared method will be

4811

# inherited.

4812

#

4813

# - If an http annotation is inherited, the path pattern will be

4814

# modified as follows. Any version prefix will be replaced by the

4815

# version of the including API plus the root path if specified.

4816

#

4817

# Example of a simple mixin:

4818

#

4819

# package google.acl.v1;

4820

# service AccessControl {

4821

# // Get the underlying ACL object.

4822

# rpc GetAcl(GetAclRequest) returns (Acl) {

4823

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4828

# service Storage {

4829

# // rpc GetAcl(GetAclRequest) returns (Acl);

4830

#

4831

# // Get a data record.

4832

# rpc GetData(GetDataRequest) returns (Data) {

4833

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4838

#

4839

# apis:

4840

# - name: google.storage.v2.Storage

4841

# mixins:

4842

# - name: google.acl.v1.AccessControl

4843

#

4844

# The mixin construct implies that all methods in `AccessControl` are

4845

# also declared with same name and request/response types in

4846

# `Storage`. A documentation generator or annotation processor will

4847

# see the effective `Storage.GetAcl` method after inherting

4848

# documentation and annotations as follows:

4849

#

4850

# service Storage {

4851

# // Get the underlying ACL object.

4852

# rpc GetAcl(GetAclRequest) returns (Acl) {

4853

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4859

#

4860

# If the `root` field in the mixin is specified, it should be a

4861

# relative path under which inherited HTTP paths are placed. Example:

4862

#

4863

# apis:

4864

# - name: google.storage.v2.Storage

4865

# mixins:

4866

# - name: google.acl.v1.AccessControl

4867

# root: acls

4868

#

4869

# This implies the following inherited HTTP annotation:

4870

#

4871

# service Storage {

4872

# // Get the underlying ACL object.

4873

# rpc GetAcl(GetAclRequest) returns (Acl) {

4874

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4879

# are rooted.

4880

"name": "A String", # The fully qualified name of the API which is included.

4881

},

4882

],

4883

"syntax": "A String", # The source syntax of the service.

4884

"version": "A String", # A version string for this api. If specified, must have the form

4885

# `major-version.minor-version`, as in `1.10`. If the minor version

4886

# is omitted, it defaults to zero. If the entire version field is

4887

# empty, the major version is derived from the package name, as

4888

# outlined below. If the field is not empty, the version in the

4889

# package name will be verified to be consistent with what is

4890

# provided here.

4891

#

4892

# The versioning schema uses [semantic

4893

# versioning](http://semver.org) where the major version number

4894

# indicates a breaking change and the minor version an additive,

4895

# non-breaking change. Both version numbers are signals to users

4896

# what to expect from different versions, and should be carefully

4897

# chosen based on the product plan.

4898

#

4899

# The major version is also reflected in the package name of the

4900

# API, which must end in `v<major-version>`, as in

4901

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4902

# be omitted. Zero major versions must only be used for

4903

# experimental, none-GA apis.

4904

"options": [ # Any metadata attached to the API.

4905

{ # A protocol buffer option, which can be attached to a message, field,

4906

# enumeration, etc.

4907

"name": "A String", # The option's name. For example, `"java_package"`.

4908

"value": { # The option's value. For example, `"com.google.protobuf"`.

4909

"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

4914

# followed by the api's simple name.

4915

},

4916

],

4917

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4918

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

4926

# - google.foo.v1.AnotherError

4927

"rules": [ # The list of custom error rules that apply to individual API messages.

4928

#

4929

# **NOTE:** All service configuration rules follow "last one wins" order.

4930

{ # A custom error rule.

4931

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4932

# objects of this type will be filtered when they appear in error payload.

4933

"selector": "A String", # Selects messages to which this rule applies.

4934

#

4935

# Refer to selector for syntax details.

4936

},

4937

],

4938

"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.

4943

# elements. Restrictions are specified using visibility labels

4944

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

4945

#

4946

# Users and projects can have access to more than one visibility label. The

4947

# effective visibility for multiple labels is the union of each label's

4948

# elements, plus any unrestricted elements.

4949

#

4950

# If an element and its parents have no restrictions, visibility is

4951

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4958

# restriction: TRUSTED_TESTER

4959

# - selector: google.calendar.Calendar.Delegate

4960

# restriction: GOOGLE_INTERNAL

4961

#

4962

# Here, all methods are publicly visible except for the restricted methods

4963

# EnhancedSearch and Delegate.

4964

"rules": [ # A list of visibility rules that apply to individual API elements.

4965

#

4966

# **NOTE:** All service configuration rules follow "last one wins" order.

4967

{ # A visibility rule provides visibility configuration for an individual API

4968

# element.

4969

"restriction": "A String", # Lists the visibility labels for this rule. Any of the listed labels grants

4970

# visibility to the element.

4971

#

4972

# If a rule has multiple labels, removing one of the labels but not all of

4973

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4980

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

4981

#

4982

# Removing GOOGLE_INTERNAL from this restriction will break clients that

4983

# rely on this method and only had access to it through GOOGLE_INTERNAL.

4984

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

4985

#

4986

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

4991

{ # Defines a metric type and its schema.

4992

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4993

# Use sentence case without an ending period, for example "Request count".

4994

"description": "A String", # A detailed description of the metric, which can be used in documentation.

4995

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

4996

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

4997

"labels": [ # The set of labels that can be used to describe a specific instance of this

4998

# metric type. For example, the

4999

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

5000

# has a label, `loadbalanced`, that specifies whether the traffic was

5001

# received through a load balanced IP address.

5002

{ # A description of a label.

5003

"valueType": "A String", # The type of data that can be assigned to the label.

5004

"description": "A String", # A human-readable description for the label.

5005

"key": "A String", # The label key.

5006

},

5007

],

5008

"type": "A String", # The metric type including a DNS name prefix, for example

5009

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

5010

# should use a natural hierarchical grouping such as the following:

5011

#

5012

# compute.googleapis.com/instance/cpu/utilization

5013

# compute.googleapis.com/instance/disk/read_ops_count

5014

# compute.googleapis.com/instance/network/received_bytes_count

5015

#

5016

# Note that if the metric type changes, the monitoring data will be

5017

# discontinued, and anything depends on it will break, such as monitoring

5018

# dashboards, alerting rules and quota limits. Therefore, once a metric has

5019

# been published, its type should be immutable.

5020

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

5021

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

5022

# supported units are a subset of [The Unified Code for Units of

5023

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5024

#

5025

# **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)

5040

# * `P` peta (10**15)

5041

# * `E` exa (10**18)

5042

# * `Z` zetta (10**21)

5043

# * `Y` yotta (10**24)

5044

# * `m` milli (10**-3)

5045

# * `u` micro (10**-6)

5046

# * `n` nano (10**-9)

5047

# * `p` pico (10**-12)

5048

# * `f` femto (10**-15)

5049

# * `a` atto (10**-18)

5050

# * `z` zepto (10**-21)

5051

# * `y` yocto (10**-24)

5052

# * `Ki` kibi (2**10)

5053

# * `Mi` mebi (2**20)

5054

# * `Gi` gibi (2**30)

5055

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5060

#

5061

# The grammar also includes these connectors:

5062

#

5063

# * `/` division (as an infix operator, e.g. `1/s`).

5064

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5065

#

5066

# The grammar for a unit is as follows:

5067

#

5068

# Expression = Component { "." Component } { "/" Component } ;

5069

#

5070

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5080

# equivalent to `1` if it is used alone. For examples,

5081

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5082

# * `NAME` is a sequence of non-blank printable ASCII characters not

5083

# containing '{' or '}'.

5084

"name": "A String", # Resource name. The format of the name may vary between different

5085

# implementations. For examples:

5086

#

5087

# projects/{project_id}/metricDescriptors/{type=**}

5088

# metricDescriptors/{type=**}

5089

},

5090

],

5091

"enums": [ # A list of all enum types included in this API service. Enums

5092

# referenced directly or indirectly by the `apis` are automatically

5093

# included. Enums which are not referenced but shall be included

5094

# should be listed here by name. Example:

5095

#

5096

# enums:

5097

# - name: google.someapi.v1.SomeEnum

5098

{ # Enum type definition.

5099

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5100

# protobuf element, like the file in which it is defined.

5101

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5102

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5103

},

5104

"enumvalue": [ # Enum value definitions.

5105

{ # Enum value definition.

5106

"number": 42, # Enum value number.

5107

"options": [ # Protocol buffer options.

5108

{ # A protocol buffer option, which can be attached to a message, field,

5109

# enumeration, etc.

5110

"name": "A String", # The option's name. For example, `"java_package"`.

5111

"value": { # The option's value. For example, `"com.google.protobuf"`.

5112

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

5117

},

5118

],

5119

"options": [ # Protocol buffer options.

5120

{ # A protocol buffer option, which can be attached to a message, field,

5121

# enumeration, etc.

5122

"name": "A String", # The option's name. For example, `"java_package"`.

5123

"value": { # The option's value. For example, `"com.google.protobuf"`.

5124

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

5129

"syntax": "A String", # The source syntax.

5130

},

5131

],

5132

"types": [ # A list of all proto message types included in this API service.

5133

# Types referenced directly or indirectly by the `apis` are

5134

# automatically included. Messages which are not referenced but

5135

# shall be included, such as types used by the `google.protobuf.Any` type,

5136

# should be listed here by name. Example:

5137

#

5138

# types:

5139

# - name: google.protobuf.Int32

5140

{ # A protocol buffer message type.

5141

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5142

"A String",

5143

],

5144

"name": "A String", # The fully qualified message name.

5145

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5146

# protobuf element, like the file in which it is defined.

5147

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5148

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5149

},

5150

"syntax": "A String", # The source syntax.

5151

"fields": [ # The list of fields.

5152

{ # A single field of a message type.

5153

"kind": "A String", # The field type.

5154

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5155

# types. The first type has index 1; zero means the type is not in the list.

5156

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5157

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5158

"name": "A String", # The field name.

5159

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5160

"jsonName": "A String", # The field JSON name.

5161

"number": 42, # The field number.

5162

"cardinality": "A String", # The field cardinality.

5163

"options": [ # The protocol buffer options.

5164

{ # A protocol buffer option, which can be attached to a message, field,

5165

# enumeration, etc.

5166

"name": "A String", # The option's name. For example, `"java_package"`.

5167

"value": { # The option's value. For example, `"com.google.protobuf"`.

5168

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5173

},

5174

],

5175

"options": [ # The protocol buffer options.

5176

{ # A protocol buffer option, which can be attached to a message, field,

5177

# enumeration, etc.

5178

"name": "A String", # The option's name. For example, `"java_package"`.

5179

"value": { # The option's value. For example, `"com.google.protobuf"`.

5180

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"logging": { # Logging configuration of the service. # Logging configuration of the service.

5187

#

5188

# The following example shows how to configure logs to be sent to the

5189

# producer and consumer projects. In the example,

5190

# the `library.googleapis.com/activity_history` log is

5191

# sent to both the producer and consumer projects, whereas

5192

# the `library.googleapis.com/purchase_history` log is only sent to the

5193

# producer project:

5194

#

5195

# monitored_resources:

5196

# - type: library.googleapis.com/branch

5197

# labels:

5198

# - key: /city

5199

# description: The city where the library branch is located in.

5200

# - key: /name

5201

# description: The name of the branch.

5202

# logs:

5203

# - name: library.googleapis.com/activity_history

5204

# labels:

5205

# - key: /customer_id

5206

# - name: library.googleapis.com/purchase_history

5207

# logging:

5208

# producer_destinations:

5209

# - monitored_resource: library.googleapis.com/branch

5210

# logs:

5211

# - library.googleapis.com/activity_history

5212

# - library.googleapis.com/purchase_history

5213

# consumer_destinations:

5214

# - monitored_resource: library.googleapis.com/branch

5215

# logs:

5216

# - library.googleapis.com/activity_history

5217

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5218

# There can be multiple producer destinations, each one must have a

5219

# different monitored resource type. A log can be used in at most

5220

# one producer destination.

5221

{ # Configuration of a specific logging destination (the producer project

5222

# or the consumer project).

5223

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5224

# Service.monitored_resources section.

5225

"logs": [ # Names of the logs to be sent to this destination. Each name must

5226

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5232

# There can be multiple consumer destinations, each one must have a

5233

# different monitored resource type. A log can be used in at most

5234

# one consumer destination.

5235

{ # Configuration of a specific logging destination (the producer project

5236

# or the consumer project).

5237

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5238

# Service.monitored_resources section.

5239

"logs": [ # Names of the logs to be sent to this destination. Each name must

5240

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

5247

# e.g. `calendar.googleapis.com`.

5248

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5249

#

5250

# Example:

5251

# <pre><code>documentation:

5252

# summary: >

5253

# The Google Calendar API gives access

5254

# to most calendar features.

5255

# pages:

5256

# - name: Overview

5257

# content: (== include google/foo/overview.md ==)

5258

# - name: Tutorial

5259

# content: (== include google/foo/tutorial.md ==)

5260

# subpages;

5261

# - name: Java

5262

# content: (== include google/foo/tutorial_java.md ==)

5263

# rules:

5264

# - selector: google.calendar.Calendar.Get

5265

# description: >

5266

# ...

5267

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5272

# standard markdown features, definition lists, tables and fenced

5273

# code blocks are supported. Section headers can be provided and are

5274

# interpreted relative to the section nesting of the context where

5275

# a documentation fragment is embedded.

5276

#

5277

# Documentation from the IDL is merged with documentation defined

5278

# via the config at normalization time, where documentation provided

5279

# by config rules overrides IDL provided.

5280

#

5281

# A number of constructs specific to the API platform are supported

5282

# in documentation text.

5283

#

5284

# In order to reference a proto element, the following

5285

# notation can be used:

5286

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5287

# To override the display text used for the link, this can be used:

5288

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5289

# Text can be excluded from doc using the following notation:

5290

# <pre><code>(-- internal comment --)</code></pre>

5291

# Comments can be made conditional using a visibility label. The below

5292

# text will be only rendered if the `BETA` label is available:

5293

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5294

# A few directives are available in documentation. Note that

5295

# directives must appear on a single line to be properly

5296

# identified. The `include` directive includes a markdown file from

5297

# an external source:

5298

# <pre><code>(== include path/to/file ==)</code></pre>

5299

# The `resource_for` directive marks a message to be the resource of

5300

# a collection in REST view. If it is not specified, tools attempt

5301

# to infer the resource from the operations in a collection:

5302

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5303

# The directive `suppress_warning` does not directly affect documentation

5304

# and is documented together with service config validation.

5305

"rules": [ # A list of documentation rules that apply to individual API elements.

5306

#

5307

# **NOTE:** All service configuration rules follow "last one wins" order.

5308

{ # A documentation rule provides information about individual API elements.

5309

"description": "A String", # Description of the selected API(s).

5310

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5311

# element is marked as `deprecated`.

5312

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5313

# qualified name of the element which may end in "*", indicating a wildcard.

5314

# Wildcards are only allowed at the end and for a whole component of the

5315

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5316

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

5321

# <pre><code>documentation:

5322

# summary: ...

5323

# overview: (== include overview.md ==)

5324

# </code></pre>

5325

# This is a shortcut for the following declaration (using pages style):

5326

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5331

# </code></pre>

5332

# Note: you cannot specify both `overview` field and `pages` field.

5333

"summary": "A String", # A short summary of what the service does. Can only be provided by

5334

# plain text.

5335

"pages": [ # The top level pages for the documentation set.

5336

{ # Represents a documentation page. A page can contain subpages to represent

5337

# nested documentation set structure.

5338

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5339

# to include content from a Markdown file.

5340

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5341

# honored in the generated docset.

5342

# Object with schema name: Page

5343

],

5344

"name": "A String", # The name of the page. It will be used as an identity of the page to

5345

# generate URI of the page, text of the link to this page in navigation,

5346

# etc. The full page name (start from the root page name to this page

5347

# concatenated with `.`) can be used as reference to the page in your

5348

# documentation. For example:

5349

# <pre><code>pages:

5350

# - name: Tutorial

5351

# content: (== include tutorial.md ==)

5352

# subpages:

5353

# - name: Java

5354

# content: (== include tutorial_java.md ==)

5355

# </code></pre>

5356

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

5361

},

5362

"systemTypes": [ # A list of all proto message types included in this API service.

5363

# It serves similar purpose as [google.api.Service.types], except that

5364

# these types are not needed by user-defined APIs. Therefore, they will not

5365

# show up in the generated discovery doc. This field should only be used

5366

# to define system APIs in ESF.

5367

{ # A protocol buffer message type.

5368

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5369

"A String",

5370

],

5371

"name": "A String", # The fully qualified message name.

5372

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5373

# protobuf element, like the file in which it is defined.

5374

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5375

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5376

},

5377

"syntax": "A String", # The source syntax.

5378

"fields": [ # The list of fields.

5379

{ # A single field of a message type.

5380

"kind": "A String", # The field type.

5381

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5382

# types. The first type has index 1; zero means the type is not in the list.

5383

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5384

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5385

"name": "A String", # The field name.

5386

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5387

"jsonName": "A String", # The field JSON name.

5388

"number": 42, # The field number.

5389

"cardinality": "A String", # The field cardinality.

5390

"options": [ # The protocol buffer options.

5391

{ # A protocol buffer option, which can be attached to a message, field,

5392

# enumeration, etc.

5393

"name": "A String", # The option's name. For example, `"java_package"`.

5394

"value": { # The option's value. For example, `"com.google.protobuf"`.

5395

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5400

},

5401

],

5402

"options": [ # The protocol buffer options.

5403

{ # A protocol buffer option, which can be attached to a message, field,

5404

# enumeration, etc.

5405

"name": "A String", # The option's name. For example, `"java_package"`.

5406

"value": { # The option's value. For example, `"com.google.protobuf"`.

5407

"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

5422

# - google.rpc.context.OriginContext

5423

#

5424

# The above specifies that all methods in the API request

5425

# `google.rpc.context.ProjectContext` and

5426

# `google.rpc.context.OriginContext`.

5427

#

5428

# Available context types are defined in package

5429

# `google.rpc.context`.

5430

"rules": [ # A list of RPC context rules that apply to individual API methods.

5431

#

5432

# **NOTE:** All service configuration rules follow "last one wins" order.

5433

{ # A context rule provides information about the context for an individual API

5434

# element.

5435

"provided": [ # A list of full type names of provided contexts.

5436

"A String",

5437

],

5438

"requested": [ # A list of full type names of requested contexts.

5439

"A String",

5440

],

5441

"selector": "A String", # Selects the methods to which this rule applies.

5442

#

5443

# Refer to selector for syntax details.

},

],

},

},

],

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

5454

<pre>Retrieves the next page of results.

5455

5456

Args:

5457

previous_request: The request for the previous page. (required)

5458

previous_response: The response from the request for the previous page. (required)

5459

5460

Returns:

5461

A request object that you can call 'execute()' on to request the next

5462

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>

5468

<pre>Creates a new service configuration (version) for a managed service based

5469

on

5470

user-supplied configuration source files (for example: OpenAPI

5471

Specification). This method stores the source configurations as well as the

5472

generated service configuration. To rollout the service configuration to

5473

other services,

5474

please call CreateServiceRollout.

5475

5476

Operation<response: SubmitConfigSourceResponse>

5477

5478

Args:

5479

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5480

for naming requirements. For example: `example.googleapis.com`. (required)

5481

body: object, The request body. (required)

5482

The object takes the form of:

5483

5484

{ # Request message for SubmitConfigSource method.

5485

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

5486

# `google.api.Service` configuration based on the `ConfigSource` provided,

5487

# but the generated config and the sources will NOT be persisted.

5488

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

5489

# defined by `google.api.Service`.

5490

"files": [ # Set of source configuration files that are used to generate a service

5491

# configuration (`google.api.Service`).

5492

{ # Generic specification of a source configuration file

5493

"fileContents": "A String", # The bytes that constitute the file.

5494

"fileType": "A String", # The type of configuration file this represents.

5495

"filePath": "A String", # The file name of the configuration file (full or relative path).

5496

},

5497

],

5498

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5499

# by the client for tracking purpose. If empty, the server may choose to

5500

# 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:

5511

5512

{ # This resource represents a long-running operation that is the result of a

5513

# network API call.

5514

"metadata": { # Service-specific metadata associated with the operation. It typically

5515

# contains progress information and common metadata such as create time.

5516

# Some services might not provide such metadata. Any method that returns a

5517

# long-running operation should document the metadata type, if any.

5518

"a_key": "", # Properties of the object. Contains field @type with type URL.

5519

},

5520

"done": True or False, # If the value is `false`, it means the operation is still in progress.

5521

# If true, the operation is completed, and either `error` or `response` is

5522

# available.

5523

"response": { # The normal response of the operation in case of success. If the original

5524

# method returns no data on success, such as `Delete`, the response is

5525

# `google.protobuf.Empty`. If the original method is standard

5526

# `Get`/`Create`/`Update`, the response should be the resource. For other

5527

# methods, the response should have the type `XxxResponse`, where `Xxx`

5528

# is the original method name. For example, if the original method name

5529

# is `TakeSnapshot()`, the inferred response type is

5530

# `TakeSnapshotResponse`.

5531

"a_key": "", # Properties of the object. Contains field @type with type URL.

5532

},

5533

"name": "A String", # The server-assigned name, which is only unique within the same service that

5534

# originally returns it. If you use the default HTTP mapping, the

5535

# `name` should have the format of `operations/some/unique/name`.

5536

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure.

5537

# programming environments, including REST APIs and RPC APIs. It is used by

5538

# [gRPC](https://github.com/grpc). The error model is designed to be:

5539

#

5540

# - Simple to use and understand for most users

5541

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

5546

# and error details. The error code should be an enum value of

5547

# google.rpc.Code, but it may accept additional error codes if needed. The

5548

# error message should be a developer-facing English message that helps

5549

# developers *understand* and *resolve* the error. If a localized user-facing

5550

# error message is needed, put the localized message in the error details or

5551

# localize it in the client. The optional error details may contain arbitrary

5552

# information about the error. There is a predefined set of error detail types

5553

# 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

5558

# is not necessarily the actual wire format. When the `Status` message is

5559

# exposed in different client libraries and different wire protocols, it can be

5560

# mapped differently. For example, it will likely be mapped to some exceptions

5561

# 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

5566

# environments, either with or without APIs, to provide a

5567

# consistent developer experience across different environments.

5568

#

5569

# Example uses of this error model include:

5570

#

5571

# - Partial errors. If a service needs to return partial errors to the client,

5572

# it may embed the `Status` in the normal response to indicate the partial

5573

# errors.

5574

#

5575

# - Workflow errors. A typical workflow has multiple steps. Each step may

5576

# have a `Status` message for error reporting purpose.

5577

#

5578

# - Batch operations. If a client uses batch request and batch response, the

5579

# `Status` message should be used directly inside batch response, one for

5580

# each error sub-response.

5581

#

5582

# - Asynchronous operations. If an API call embeds asynchronous operation

5583

# results in its response, the status of those operations should be

5584

# represented directly using the `Status` message.

5585

#

5586

# - Logging. If some API errors are stored in logs, the message `Status` could

5587

# be used directly after any stripping needed for security/privacy reasons.

5588

"message": "A String", # A developer-facing error message, which should be in English. Any

5589

# user-facing error message should be localized and sent in the

5590

# google.rpc.Status.details field, or localized by the client.

5591

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

5592

"details": [ # A list of messages that carry the error details. There will be a

5593

# common set of message types for APIs to use.

5594

{

5595

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

],

},

}</pre>

</div>

</body></html>