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

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

[diff] [blame]

76

<h2>Instance Methods</h2>

77

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

78

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

Jon Wayne Parrott

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

[diff] [blame]

79

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

80

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

81

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

Jon Wayne Parrott

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

[diff] [blame]

82

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

83

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

84

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

Jon Wayne Parrott

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

[diff] [blame]

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

90

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

Jon Wayne Parrott

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

[diff] [blame]

91

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

92

<h3>Method Details</h3>

93

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

94

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

Jon Wayne Parrott

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

[diff] [blame]

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

100

Only the 100 most recent service configurations and ones referenced by

101

existing rollouts are kept for each service. The rest will be deleted

102

eventually.

103

Jon Wayne Parrott

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

[diff] [blame]

104

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

105

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

Jon Wayne Parrott

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

[diff] [blame]

106

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

107

body: object, The request body.

Jon Wayne Parrott

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

[diff] [blame]

108

The object takes the form of:

109

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

110

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

111

# describes basic information about a service, such as the name and the

112

# title, and delegates other aspects to sub-sections. Each sub-section is

113

# either a proto message or a repeated proto message that configures a

114

# specific aspect, such as auth. See each proto message definition for details.

Jon Wayne Parrott

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

[diff] [blame]

#

# Example:

#

# type: google.api.Service

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

119

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

120

# name: calendar.googleapis.com

121

# title: Google Calendar API

122

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

123

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

124

# authentication:

125

# providers:

126

# - id: google_calendar_auth

127

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

128

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

Jon Wayne Parrott

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

[diff] [blame]

129

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

130

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

131

# requirements:

132

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

133

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

Jon Wayne Parrott

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

[diff] [blame]

134

#

135

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

136

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

137

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

138

# to both producer and consumer projects, whereas the

139

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

140

# consumer project.

141

#

142

# monitored_resources:

143

# - type: library.googleapis.com/branch

144

# labels:

145

# - key: /city

146

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

147

# - key: /name

148

# description: The name of the branch.

149

# metrics:

150

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

155

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

160

# monitoring:

161

# producer_destinations:

162

# - monitored_resource: library.googleapis.com/branch

163

# metrics:

164

# - library.googleapis.com/book/returned_count

165

# consumer_destinations:

166

# - monitored_resource: library.googleapis.com/branch

167

# metrics:

168

# - library.googleapis.com/book/returned_count

169

# - library.googleapis.com/book/overdue_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

170

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

171

# There can be multiple consumer destinations. A monitored resouce type may

172

# appear in multiple monitoring destinations if different aggregations are

173

# needed for different sets of metrics associated with that monitored

174

# resource type. A monitored resource and metric pair may only be used once

175

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

176

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

177

# or the consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

178

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

Jon Wayne Parrott

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

[diff] [blame]

179

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

180

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

181

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

"A String",

],

},

],

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

187

# There can be multiple producer destinations. A monitored resouce type may

188

# appear in multiple monitoring destinations if different aggregations are

189

# needed for different sets of metrics associated with that monitored

190

# resource type. A monitored resource and metric pair may only be used once

191

# in the Monitoring configuration.

192

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

193

# or the consumer project).

194

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

195

# Service.monitored_resources section.

196

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

197

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

198

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

],

},

],

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

203

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

204

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

205

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

206

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

207

# to define system APIs in ESF.

208

{ # A protocol buffer message type.

209

"options": [ # The protocol buffer options.

210

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

211

# enumeration, etc.

212

"value": { # The option's value packed in an Any message. If the value is a primitive,

213

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

214

# should be used. If the value is an enum, it should be stored as an int32

215

# value using the google.protobuf.Int32Value type.

216

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

217

},

218

"name": "A String", # The option's name. For protobuf built-in options (options defined in

219

# descriptor.proto), this is the short name. For example, `"map_entry"`.

220

# For custom options, it should be the fully-qualified name. For example,

221

# `"google.api.http"`.

222

},

223

],

224

"fields": [ # The list of fields.

225

{ # A single field of a message type.

226

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

227

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

228

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

229

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

230

"number": 42, # The field number.

231

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

232

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

233

"options": [ # The protocol buffer options.

234

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

235

# enumeration, etc.

236

"value": { # The option's value packed in an Any message. If the value is a primitive,

237

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

238

# should be used. If the value is an enum, it should be stored as an int32

239

# value using the google.protobuf.Int32Value type.

240

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

241

},

242

"name": "A String", # The option's name. For protobuf built-in options (options defined in

243

# descriptor.proto), this is the short name. For example, `"map_entry"`.

244

# For custom options, it should be the fully-qualified name. For example,

245

# `"google.api.http"`.

246

},

247

],

248

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

249

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

250

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

251

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

252

},

253

],

254

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

255

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

256

"A String",

257

],

258

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

259

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

260

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

261

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

262

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

},

},

],

"producerProjectId": "A String", # The Google project that owns this service.

267

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

268

# usage.

269

#

270

# The metric based quota configuration works this way:

271

# - The service configuration defines a set of metrics.

272

# - For API calls, the quota.metric_rules maps methods to metrics with

273

# corresponding costs.

274

# - The quota.limits defines limits on the metrics, which will be used for

275

# quota checks at runtime.

276

#

277

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

283

# metric: library.googleapis.com/write_calls

284

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

290

# # except for the UpdateBook and DeleteBook methods. These two methods

291

# # are mapped to the write_calls metric, with the UpdateBook method

292

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

297

# - selector: google.example.library.v1.LibraryService.UpdateBook

298

# metric_costs:

299

# library.googleapis.com/write_calls: 2

300

# - selector: google.example.library.v1.LibraryService.DeleteBook

301

# metric_costs:

302

# library.googleapis.com/write_calls: 1

303

#

304

# Corresponding Metric definition:

305

#

306

# metrics:

307

# - name: library.googleapis.com/read_calls

308

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

313

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

318

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

319

# for a limit type. There can be at most one limit for a duration and limit

320

# type combination defined within a `QuotaGroup`.

321

"name": "A String", # Name of the quota limit.

322

#

323

# The name must be provided, and it must be unique within the service. The

324

# name can only include alphanumeric characters as well as '-'.

325

#

326

# The maximum length of the limit name is 64 characters.

327

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

328

# The free tier is the number of tokens that will be subtracted from the

329

# billed amount when billing is enabled.

330

# This field can only be set on a limit with duration "1d", in a billable

331

# group; it is invalid on any other limit. If this field is not set, it

332

# defaults to 0, indicating that there is no free tier for this service.

333

#

334

# Used by group-based quotas only.

335

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

336

#

337

# Used by group-based quotas only.

338

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

339

# duration. This is the number of tokens assigned when a client

340

# application developer activates the service for his/her project.

341

#

342

# Specifying a value of 0 will block all requests. This can be used if you

343

# are provisioning quota to selected consumers and blocking others.

344

# Similarly, a value of -1 will indicate an unlimited quota. No other

345

# negative values are allowed.

346

#

347

# Used by group-based quotas only.

348

"description": "A String", # Optional. User-visible, extended description for this quota limit.

349

# Should be used only when more context is needed to understand this limit

350

# than provided by the limit's display name (see: `display_name`).

351

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

352

# the same metric will be checked together during runtime. The metric must be

353

# defined within the service config.

354

"displayName": "A String", # User-visible display name for this limit.

355

# Optional. If not set, the UI will provide a default display name based on

356

# the quota configuration. This field can be used to override the default

357

# display name generated from the configuration.

358

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

359

# integer value that is the maximum number of requests allowed for the

360

# specified unit. Currently only STANDARD is supported.

361

"a_key": "A String",

362

},

363

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

364

# Metric.unit. The supported unit kinds are determined by the quota

365

# backend system.

366

#

367

# Here are some examples:

368

# * "1/min/{project}" for quota per minute per project.

369

#

370

# Note: the order of unit components is insignificant.

371

# The "1" at the beginning is required to follow the metric unit syntax.

372

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

373

# duration. Client application developers can override the default limit up

374

# to this maximum. If specified, this value cannot be set to a value less

375

# than the default limit. If not specified, it is set to the default limit.

376

#

377

# To allow clients to apply overrides with no upper bound, set this to -1,

378

# indicating unlimited maximum quota.

379

#

380

# Used by group-based quotas only.

381

},

382

],

383

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

384

# or more metrics.

385

{ # Bind API methods to metrics. Binding a method to a metric causes that

386

# metric's configured quota behaviors to apply to the method call.

387

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

388

#

389

# Refer to selector for syntax details.

390

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

391

# cost applied to each metric.

392

#

393

# The key of the map is the metric name, and the values are the amount

394

# increased for the metric against which the quota limits are defined.

395

# The value must not be negative.

"a_key": "A String",

},

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

402

# service, such as `calendar.googleapis.com`. The service name

403

# typically goes through DNS verification to make sure the owner

404

# of the service also owns the DNS name.

405

"billing": { # Billing related configuration of the service. # Billing configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

406

#

407

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

408

# for billing, `consumer_destinations` is the only supported destination and

409

# the monitored resources need at least one label key

410

# `cloud.googleapis.com/location` to indicate the location of the billing

411

# usage, using different monitored resources between monitoring and billing is

412

# recommended so they can be evolved independently:

413

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

414

#

415

# monitored_resources:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

416

# - type: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

417

# labels:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

418

# - key: cloud.googleapis.com/location

419

# description: |

420

# Predefined label to support billing location restriction.

421

# - key: city

422

# description: |

423

# Custom label to define the city where the library branch is located

424

# in.

425

# - key: name

426

# description: Custom label to define the name of the library branch.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

427

# metrics:

428

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

429

# metric_kind: DELTA

430

# value_type: INT64

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

431

# unit: "1"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

432

# billing:

433

# consumer_destinations:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

434

# - monitored_resource: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

435

# metrics:

436

# - library.googleapis.com/book/borrowed_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

437

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

438

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

439

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

440

# one consumer destination.

441

{ # Configuration of a specific billing destination (Currently only support

442

# bill against consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

443

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

444

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

445

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

446

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

447

"A String",

448

],

Jon Wayne Parrott

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

[diff] [blame]

449

},

450

],

451

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

452

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

453

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

454

# error responses.

Jon Wayne Parrott

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

[diff] [blame]

455

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

456

# Example:

Jon Wayne Parrott

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

[diff] [blame]

457

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

458

# custom_error:

459

# types:

460

# - google.foo.v1.CustomError

461

# - google.foo.v1.AnotherError

462

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

Jon Wayne Parrott

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

[diff] [blame]

463

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

464

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

465

{ # A custom error rule.

466

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

467

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

468

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

Jon Wayne Parrott

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

[diff] [blame]

469

#

470

# Refer to selector for syntax details.

471

},

472

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

473

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

474

"A String",

Jon Wayne Parrott

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

[diff] [blame]

475

],

476

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

477

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

478

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

479

# with the same name as the service is automatically generated to service all

480

# defined APIs.

481

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

482

# A service may expose any number of endpoints, and all endpoints share the

483

# same service configuration, such as quota configuration and monitoring

484

# configuration.

Jon Wayne Parrott

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

[diff] [blame]

485

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

486

# Example service configuration:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

487

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

488

# name: library-example.googleapis.com

489

# endpoints:

490

# # Below entry makes 'google.example.library.v1.Library'

491

# # API be served from endpoint address library-example.googleapis.com.

492

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

493

# # it to decide whether the subsequent cross-origin request is

494

# # allowed to proceed.

495

# - name: library-example.googleapis.com

496

# allow_cors: true

497

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

498

# please specify multiple google.api.Endpoint for each of the intended

499

# aliases.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

500

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

501

# Additional names that this endpoint will be hosted on.

502

"A String",

503

],

504

"features": [ # The list of features enabled on this endpoint.

505

"A String",

506

],

507

"allowCors": True or False, # Allowing

508

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

509

# cross-domain traffic, would allow the backends served from this endpoint to

510

# receive and respond to HTTP OPTIONS requests. The response will be used by

511

# the browser to determine whether the subsequent cross-origin request is

512

# allowed to proceed.

513

"name": "A String", # The canonical name of this endpoint.

514

"target": "A String", # The specification of an Internet routable address of API frontend that will

515

# handle requests to this [API

516

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

517

# either a valid IPv4 address or a fully-qualified domain name. For example,

518

# "8.8.8.8" or "myservice.appspot.com".

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

519

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

520

],

521

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

522

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

523

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

524

# - name: library.googleapis.com/activity_history

525

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

526

# display_name: Activity

527

# labels:

528

# - key: /customer_id

529

# description: Identifier of a library customer

530

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

531

# Runtime requests that contain labels not specified here are

532

# considered invalid.

533

{ # A description of a label.

534

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

535

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

536

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

537

},

538

],

539

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

540

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

541

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

542

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

543

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

544

# the documentation and can contain details.

545

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

546

# the user interface and should be concise.

547

},

548

],

549

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

550

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

551

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

552

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

553

# which cannot be resolved against the associated IDL files.

554

{ # Api is a light-weight descriptor for an API Interface.

555

#

556

# Interfaces are also described as "protocol buffer services" in some contexts,

557

# such as by the "service" keyword in a .proto file, but they are different

558

# from API Services, which represent a concrete implementation of an interface

559

# as opposed to simply a description of methods and bindings. They are also

560

# sometimes simply referred to as "APIs" in other contexts, such as the name of

561

# this message itself. See https://cloud.google.com/apis/design/glossary for

562

# detailed terminology.

563

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

564

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

565

# enumeration, etc.

566

"value": { # The option's value packed in an Any message. If the value is a primitive,

567

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

568

# should be used. If the value is an enum, it should be stored as an int32

569

# value using the google.protobuf.Int32Value type.

570

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

571

},

572

"name": "A String", # The option's name. For protobuf built-in options (options defined in

573

# descriptor.proto), this is the short name. For example, `"map_entry"`.

574

# For custom options, it should be the fully-qualified name. For example,

575

# `"google.api.http"`.

576

},

577

],

578

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

579

{ # Method represents a method of an API interface.

580

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

581

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

582

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

583

# enumeration, etc.

584

"value": { # The option's value packed in an Any message. If the value is a primitive,

585

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

586

# should be used. If the value is an enum, it should be stored as an int32

587

# value using the google.protobuf.Int32Value type.

588

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

589

},

590

"name": "A String", # The option's name. For protobuf built-in options (options defined in

591

# descriptor.proto), this is the short name. For example, `"map_entry"`.

592

# For custom options, it should be the fully-qualified name. For example,

593

# `"google.api.http"`.

594

},

595

],

596

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

597

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

598

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

599

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

600

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

601

},

602

],

603

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

604

# followed by the interface's simple name.

605

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

606

# message.

607

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

608

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

609

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

610

},

611

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

612

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

613

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

614

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

615

# major version is derived from the package name, as outlined below. If the

616

# field is not empty, the version in the package name will be verified to be

617

# consistent with what is provided here.

618

#

619

# The versioning schema uses [semantic

620

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

621

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

622

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

623

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

624

# chosen based on the product plan.

625

#

626

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

627

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

628

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

629

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

630

# experimental, non-GA interfaces.

631

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

632

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

633

# interface must redeclare all the methods from the included interface, but

634

# documentation and options are inherited as follows:

635

#

636

# - If after comment and whitespace stripping, the documentation

637

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

638

# from the original method.

639

#

640

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

641

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

642

# inherited.

643

#

644

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

645

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

646

# version of the including interface plus the root path if

647

# specified.

648

#

649

# Example of a simple mixin:

650

#

651

# package google.acl.v1;

652

# service AccessControl {

653

# // Get the underlying ACL object.

654

# rpc GetAcl(GetAclRequest) returns (Acl) {

655

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

# }

# }

#

# package google.storage.v2;

660

# service Storage {

661

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

662

#

663

# // Get a data record.

664

# rpc GetData(GetDataRequest) returns (Data) {

665

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

# }

# }

#

# Example of a mixin configuration:

670

#

671

# apis:

672

# - name: google.storage.v2.Storage

673

# mixins:

674

# - name: google.acl.v1.AccessControl

675

#

676

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

677

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

678

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

679

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

680

# documentation and annotations as follows:

681

#

682

# service Storage {

683

# // Get the underlying ACL object.

684

# rpc GetAcl(GetAclRequest) returns (Acl) {

685

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

# }

# ...

# }

#

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

691

#

692

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

693

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

694

#

695

# apis:

696

# - name: google.storage.v2.Storage

697

# mixins:

698

# - name: google.acl.v1.AccessControl

699

# root: acls

700

#

701

# This implies the following inherited HTTP annotation:

702

#

703

# service Storage {

704

# // Get the underlying ACL object.

705

# rpc GetAcl(GetAclRequest) returns (Acl) {

706

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

# }

# ...

# }

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

711

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

# are rooted.

},

],

},

],

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

718

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

719

# automatically included. Messages which are not referenced but

720

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

721

# should be listed here by name. Example:

722

#

723

# types:

724

# - name: google.protobuf.Int32

725

{ # A protocol buffer message type.

726

"options": [ # The protocol buffer options.

727

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

728

# enumeration, etc.

729

"value": { # The option's value packed in an Any message. If the value is a primitive,

730

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

731

# should be used. If the value is an enum, it should be stored as an int32

732

# value using the google.protobuf.Int32Value type.

733

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

734

},

735

"name": "A String", # The option's name. For protobuf built-in options (options defined in

736

# descriptor.proto), this is the short name. For example, `"map_entry"`.

737

# For custom options, it should be the fully-qualified name. For example,

738

# `"google.api.http"`.

739

},

740

],

741

"fields": [ # The list of fields.

742

{ # A single field of a message type.

743

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

744

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

745

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

746

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

747

"number": 42, # The field number.

748

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

749

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

750

"options": [ # The protocol buffer options.

751

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

752

# enumeration, etc.

753

"value": { # The option's value packed in an Any message. If the value is a primitive,

754

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

755

# should be used. If the value is an enum, it should be stored as an int32

756

# value using the google.protobuf.Int32Value type.

757

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

758

},

759

"name": "A String", # The option's name. For protobuf built-in options (options defined in

760

# descriptor.proto), this is the short name. For example, `"map_entry"`.

761

# For custom options, it should be the fully-qualified name. For example,

762

# `"google.api.http"`.

763

},

764

],

765

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

766

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

767

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

768

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

769

},

770

],

771

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

772

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

773

"A String",

774

],

775

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

776

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

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

},

},

],

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

784

"sourceFiles": [ # All files used during config generation.

785

{

786

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

787

},

Jon Wayne Parrott

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

[diff] [blame]

788

],

789

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

790

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

Jon Wayne Parrott

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

[diff] [blame]

791

# HttpRule, each specifying the mapping of an RPC method

792

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

793

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

794

# cases of single segment matches in reserved expansion, where "%2F" will be

795

# left encoded.

Jon Wayne Parrott

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

[diff] [blame]

796

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

797

# The default behavior is to not decode RFC 6570 reserved characters in multi

798

# segment matches.

799

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

800

#

801

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

802

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

803

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

804

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

805

# more HTTP REST endpoints. It allows developers to build a single API service

806

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

807

# APIs](https://github.com/googleapis/googleapis),

808

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

809

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

810

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

811

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

812

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

813

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

814

# how different portions of the gRPC request message are mapped to the URL

815

# path, URL query parameters, and HTTP request body. It also controls how the

816

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

817

# typically specified as an `google.api.http` annotation on the gRPC method.

818

#

819

# Each mapping specifies a URL path template and an HTTP method. The path

820

# template may refer to one or more fields in the gRPC request message, as long

821

# as each field is a non-repeated field with a primitive (non-message) type.

822

# The path template controls how fields of the request message are mapped to

823

# the URL path.

824

#

825

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

826

#

827

# service Messaging {

828

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

829

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

830

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

831

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

832

# }

833

# }

834

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

835

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

836

# }

837

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

838

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

839

# }

840

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

841

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

842

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

843

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

844

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

845

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

Jon Wayne Parrott

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

[diff] [blame]

846

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

847

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

848

# automatically become HTTP query parameters if there is no HTTP request body.

849

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

850

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

851

# service Messaging {

852

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

853

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

854

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

855

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

856

# }

857

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

858

# message GetMessageRequest {

859

# message SubMessage {

860

# string subfield = 1;

861

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

862

# string message_id = 1; // Mapped to URL path.

863

# int64 revision = 2; // Mapped to URL query parameter `revision`.

864

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

865

# }

866

#

Jon Wayne Parrott

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

[diff] [blame]

867

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

868

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

869

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

870

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

871

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

872

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

873

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

874

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

875

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

876

# primitive type or a repeated primitive type or a non-repeated message type.

877

# In the case of a repeated type, the parameter can be repeated in the URL

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

878

# as `...?param=A&param=B`. In the case of a message type, each field of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

879

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

880

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

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

[diff] [blame]

881

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

882

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

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

[diff] [blame]

883

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

884

# message resource collection:

885

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

886

# service Messaging {

887

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

888

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

889

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

890

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

895

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

896

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

897

# }

898

#

Jon Wayne Parrott

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

[diff] [blame]

899

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

900

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

901

# protos JSON encoding:

902

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

903

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

904

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

905

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

906

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

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

[diff] [blame]

907

#

908

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

909

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

910

# request body. This enables the following alternative definition of

911

# the update method:

912

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

913

# service Messaging {

914

# rpc UpdateMessage(Message) returns (Message) {

915

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

916

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

917

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

923

# string text = 2;

924

# }

925

#

Jon Wayne Parrott

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

[diff] [blame]

926

#

927

# The following HTTP JSON to RPC mapping is enabled:

928

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

929

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

930

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

931

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

932

# "123456" text: "Hi!")`

Jon Wayne Parrott

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

[diff] [blame]

933

#

934

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

935

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

936

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

Jon Wayne Parrott

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

[diff] [blame]

937

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

938

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

Jon Wayne Parrott

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

[diff] [blame]

939

#

940

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

941

# the `additional_bindings` option. Example:

942

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

943

# service Messaging {

944

# rpc GetMessage(GetMessageRequest) returns (Message) {

945

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

946

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

947

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

948

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

949

# }

950

# };

Jon Wayne Parrott

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

[diff] [blame]

951

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

952

# }

953

# message GetMessageRequest {

954

# string message_id = 1;

955

# string user_id = 2;

956

# }

957

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

958

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

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

[diff] [blame]

959

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

960

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

961

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

962

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

963

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

964

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

965

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

966

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

967

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

968

# 1. Leaf request fields (recursive expansion nested messages in the request

969

# message) are classified into three categories:

970

# - Fields referred by the path template. They are passed via the URL path.

971

# - Fields referred by the HttpRule.body. They are passed via the HTTP

972

# request body.

973

# - All other fields are passed via the URL query parameters, and the

974

# parameter name is the field path in the request message. A repeated

975

# field can be represented as multiple query parameters under the same

976

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

977

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

978

# are passed via URL path and HTTP request body.

979

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

980

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

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

[diff] [blame]

981

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

982

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

983

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

984

# Template = "/" Segments [ Verb ] ;

985

# Segments = Segment { "/" Segment } ;

986

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

987

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

988

# FieldPath = IDENT { "." IDENT } ;

989

# Verb = ":" LITERAL ;

Jon Wayne Parrott

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

[diff] [blame]

990

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

991

# The syntax `*` matches a single URL path segment. The syntax `**` matches

992

# zero or more URL path segments, which must be the last part of the URL path

993

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

994

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

995

# The syntax `Variable` matches part of the URL path as specified by its

996

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

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

[diff] [blame]

997

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

998

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

999

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1000

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

1001

# contains any reserved character, such characters should be percent-encoded

1002

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

1003

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1004

# If a variable contains exactly one path segment, such as `"{var}"` or

1005

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1006

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

1007

# server side does the reverse decoding. Such variables show up in the

1008

# [Discovery

1009

# Document](https://developers.google.com/discovery/v1/reference/apis) as

1010

# `{var}`.

1011

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1012

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

1013

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1014

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1015

# The server side does the reverse decoding, except "%2F" and "%2f" are left

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1016

# unchanged. Such variables show up in the

1017

# [Discovery

1018

# Document](https://developers.google.com/discovery/v1/reference/apis) as

1019

# `{+var}`.

1020

#

1021

# ## Using gRPC API Service Configuration

1022

#

1023

# gRPC API Service Configuration (service config) is a configuration language

1024

# for configuring a gRPC service to become a user-facing product. The

1025

# service config is simply the YAML representation of the `google.api.Service`

1026

# proto message.

1027

#

1028

# As an alternative to annotating your proto file, you can configure gRPC

1029

# transcoding in your service config YAML files. You do this by specifying a

1030

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

1031

# effect as the proto annotation. This can be particularly useful if you

1032

# have a proto that is reused in multiple services. Note that any transcoding

1033

# specified in the service config will override any matching transcoding

1034

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

1041

# - selector: example.v1.Messaging.GetMessage

1042

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

1047

# proto to JSON conversion must follow the [proto3

1048

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

1049

#

1050

# While the single segment variable follows the semantics of

1051

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

1052

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

1053

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

1054

# does not expand special characters like `?` and `#`, which would lead

1055

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

1056

# for multi segment variables.

1057

#

1058

# The path variables **must not** refer to any repeated or mapped field,

1059

# because client libraries are not capable of handling such variable expansion.

1060

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1061

# The path variables **must not** capture the leading "/" character. The reason

1062

# is that the most common use case "{var}" does not capture the leading "/"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1063

# character. For consistency, all path variables must share the same behavior.

1064

#

1065

# Repeated message fields must not be mapped to URL query parameters, because

1066

# no client library can support such complicated mapping.

1067

#

1068

# If an API needs to use a JSON array for request or response body, it can map

1069

# the request or response body to a repeated field. However, some gRPC

1070

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1071

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

1072

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

Jon Wayne Parrott

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

[diff] [blame]

1073

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

1074

# the nesting may only be one level deep).

1075

# Object with schema name: HttpRule

1076

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1077

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1078

# response body. When omitted, the entire response message will be used

1079

# as the HTTP response body.

1080

#

1081

# NOTE: The referred field must be present at the top-level of the response

1082

# message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1083

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

1084

# body, or `*` for mapping all request fields not captured by the path

1085

# pattern to the HTTP body, or omitted for not having any HTTP request body.

1086

#

1087

# NOTE: the referred field must be present at the top-level of the request

1088

# message type.

1089

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

1090

#

1091

# Refer to selector for syntax details.

1092

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

1093

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

1094

# included in the `pattern` field, such as HEAD, or "*" to leave the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1095

# HTTP method unspecified for this rule. The wild-card rule is useful

1096

# for services that provide content to Web (HTML) clients.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1097

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

1098

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

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1099

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1100

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

1101

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

1102

# resources.

1103

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

1104

# half-duplex streaming method.

1105

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Jon Wayne Parrott

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

[diff] [blame]

1106

},

1107

],

1108

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1109

"systemParameters": { # ### System parameter configuration # System parameter configuration.

1110

#

1111

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

1112

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

1113

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

1114

# change the names of the system parameters.

1115

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1116

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1117

# The parameters defined here will override the default parameters

1118

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

1119

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

1120

# and names is implementation-dependent.

1121

#

1122

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1130

#

1131

#

1132

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1137

# parameters:

1138

# - name: api_key

1139

# http_header: Api-Key1

1140

# - name: api_key

1141

# http_header: Api-Key2

1142

#

1143

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

1144

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

1145

# methods.

1146

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

1147

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

1148

# names are used the behavior is implementation-dependent.

1149

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

1150

# parameter-dependent.

1151

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

1152

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

1153

# is implementation-dependent.

1154

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

1155

# insensitive.

1156

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

1157

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

1158

# sensitive.

Jon Wayne Parrott

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

[diff] [blame]

1159

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1160

],

1161

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

1162

# methods in all APIs.

1163

#

1164

# Refer to selector for syntax details.

},

],

},

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

1169

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

1170

#

1171

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

1172

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

1173

"protocol": "A String", # The protocol used for sending a request to the backend.

1174

# The supported values are "http/1.1" and "h2".

1175

#

1176

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

1186

# to "h2" for improved performance.

1187

#

1188

# Configuring this field to non-default values is only supported for secure

1189

# HTTP backends. This field will be ignored for all other backends.

1190

#

1191

# See

1192

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

1193

# for more details on the supported values.

1194

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

1195

#

1196

# Refer to selector for syntax details.

1197

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

1198

# operation. The default is no deadline.

1199

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

1200

# varies based on the request protocol and deployment environment.

1201

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

1202

# value lower than this will be rejected.

1203

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

1204

#

1205

# The scheme is used to determine the backend protocol and security.

1206

# The following schemes are accepted:

1207

#

1208

# SCHEME PROTOCOL SECURITY

# http:// HTTP None

# https:// HTTP TLS

# grpc:// gRPC None

# grpcs:// gRPC TLS

#

# It is recommended to explicitly include a scheme. Leaving out the scheme

1215

# may cause constrasting behaviors across platforms.

1216

#

1217

# If the port is unspecified, the default is:

1218

# - 80 for schemes without TLS

1219

# - 443 for schemes with TLS

1220

#

1221

# For HTTP backends, use protocol

1222

# to specify the protocol version.

1223

"pathTranslation": "A String",

1224

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

1225

# This ID token will be added in the HTTP "authorization" header, and sent

1226

# to the backend.

1227

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

1228

# original "Authorization" HTTP header will be preserved. If the header is

1229

# used to carry the original token and is expected by the backend, this

1230

# field must be set to true to preserve the header.

1231

"renameTo": "A String", # Unimplemented. Do not use.

1232

#

1233

# The new name the selected proto elements should be renamed to.

1234

#

1235

# The package, the service and the method can all be renamed.

1236

# The backend server should implement the renamed proto. However, clients

1237

# should call the original method, and ESF routes the traffic to the renamed

1238

# method.

1239

#

1240

# HTTP clients should call the URL mapped to the original method.

1241

# gRPC and Stubby clients should call the original method with package name.

1242

#

1243

# For legacy reasons, ESF allows Stubby clients to call with the

1244

# short name (without the package name). However, for API Versioning(or

1245

# multiple methods mapped to the same short name), all Stubby clients must

1246

# call the method's full name with the package name, otherwise the first one

1247

# (selector) wins.

1248

#

1249

# If this `rename_to` is specified with a trailing `*`, the `selector` must

1250

# be specified with a trailing `*` as well. The all element short names

1251

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

1257

# rename_to: google.example.library.*

1258

#

1259

# The selector matches `google.example.library.v1.Library.CreateShelf` and

1260

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

1261

# `google.example.library.Library.CreateShelf` and

1262

# `google.example.library.Library.CreateBook`. It essentially renames the

1263

# proto package name section of the matched proto service and methods.

},

],

},

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

1268

#

1269

# Example:

1270

# <pre><code>documentation:

1271

# summary: >

1272

# The Google Calendar API gives access

1273

# to most calendar features.

1274

# pages:

1275

# - name: Overview

1276

# content: &#40;== include google/foo/overview.md ==&#41;

1277

# - name: Tutorial

1278

# content: &#40;== include google/foo/tutorial.md ==&#41;

1279

# subpages;

1280

# - name: Java

1281

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

1282

# rules:

1283

# - selector: google.calendar.Calendar.Get

1284

# description: >

1285

# ...

1286

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1291

# standard markdown features, definition lists, tables and fenced

1292

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

1293

# interpreted relative to the section nesting of the context where

1294

# a documentation fragment is embedded.

1295

#

1296

# Documentation from the IDL is merged with documentation defined

1297

# via the config at normalization time, where documentation provided

1298

# by config rules overrides IDL provided.

1299

#

1300

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

1301

# in documentation text.

1302

#

1303

# In order to reference a proto element, the following

1304

# notation can be used:

1305

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

1306

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

1307

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

1308

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

1309

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

1310

#

1311

# A few directives are available in documentation. Note that

1312

# directives must appear on a single line to be properly

1313

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

1314

# an external source:

1315

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

1316

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

1317

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

1318

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

1319

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

1320

# The directive `suppress_warning` does not directly affect documentation

1321

# and is documented together with service config validation.

1322

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

1323

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

1324

#

1325

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

1326

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

1327

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

1328

# an element is marked as `deprecated`.

1329

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

1330

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

1331

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

1332

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

1333

# wildcard will match one or more components. To specify a default for all

1334

# applicable elements, the whole pattern "*" is used.

1335

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

1336

},

1337

],

1338

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

1339

# plain text.

1340

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

1341

# <pre><code>documentation:

1342

# summary: ...

1343

# overview: &#40;== include overview.md ==&#41;

1344

# </code></pre>

1345

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

1346

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

1351

# </code></pre>

1352

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

1353

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

1354

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

1355

# nested documentation set structure.

1356

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

1357

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

1358

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

1359

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

1360

# documentation. For example:

1361

# <pre><code>pages:

1362

# - name: Tutorial

1363

# content: &#40;== include tutorial.md ==&#41;

1364

# subpages:

1365

# - name: Java

1366

# content: &#40;== include tutorial_java.md ==&#41;

1367

# </code></pre>

1368

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

1369

# `Java`.

1370

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

1371

# ==&#41;</code> to include content from a Markdown file.

1372

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

1373

# honored in the generated docset.

1374

# Object with schema name: Page

],

},

],

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

1379

# from the yaml file) is not suitable. This can be seen in any fully

1380

# specified service urls as well as sections that show a base that other

1381

# urls are relative to.

1382

},

1383

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

1384

#

1385

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

1386

# producer and consumer projects. In the example, the `activity_history`

1387

# log is sent to both the producer and consumer projects, whereas the

1388

# `purchase_history` log is only sent to the producer project.

1389

#

1390

# monitored_resources:

1391

# - type: library.googleapis.com/branch

1392

# labels:

1393

# - key: /city

1394

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

1395

# - key: /name

1396

# description: The name of the branch.

1397

# logs:

1398

# - name: activity_history

1399

# labels:

1400

# - key: /customer_id

1401

# - name: purchase_history

1402

# logging:

1403

# producer_destinations:

1404

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

1409

# - monitored_resource: library.googleapis.com/branch

1410

# logs:

1411

# - activity_history

1412

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

1413

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

1414

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

1415

# one producer destination.

1416

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

1417

# or the consumer project).

1418

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

1419

# be defined in the Service.logs section. If the log name is

1420

# not a domain scoped name, it will be automatically prefixed with

1421

# the service name followed by "/".

1422

"A String",

1423

],

1424

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

1425

# Service.monitored_resources section.

1426

},

1427

],

1428

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

1429

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

1430

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

1431

# one consumer destination.

1432

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

1433

# or the consumer project).

1434

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

1435

# be defined in the Service.logs section. If the log name is

1436

# not a domain scoped name, it will be automatically prefixed with

1437

# the service name followed by "/".

1438

"A String",

1439

],

1440

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

1441

# Service.monitored_resources section.

},

],

},

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

1446

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

1447

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

1448

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

1449

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

1450

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

1451

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

1452

#

1453

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

1454

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

1455

# by the API.

1456

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

1457

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

1458

# without any article or other determiners. For example,

1459

# `"Google Cloud SQL Database"`.

1460

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

1461

# be used in documentation.

1462

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

1463

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

1464

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

1465

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

1466

{ # A description of a label.

1467

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

1468

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

1469

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

Jon Wayne Parrott

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

[diff] [blame]

1470

},

1471

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1472

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

1473

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

1474

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

1475

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

1476

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

1477

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

1478

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

1479

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

1480

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

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

[diff] [blame]

1481

},

1482

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1483

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

Jon Wayne Parrott

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

[diff] [blame]

1484

#

1485

# Example:

1486

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

1492

# - google.rpc.context.OriginContext

1493

#

1494

# The above specifies that all methods in the API request

1495

# `google.rpc.context.ProjectContext` and

1496

# `google.rpc.context.OriginContext`.

1497

#

1498

# Available context types are defined in package

1499

# `google.rpc.context`.

1500

#

1501

# This also provides mechanism to whitelist any protobuf message extension that

1502

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

1503

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

1504

# specific protobuf types that can appear in grpc metadata as follows in your

# yaml file:

#

# Example:

#

# context:

# rules:

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

1512

# allowed_request_extensions:

1513

# - google.foo.v1.NewExtension

1514

# allowed_response_extensions:

1515

# - google.foo.v1.NewExtension

1516

#

1517

# You can also specify extension ID instead of fully qualified extension name

1518

# here.

1519

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

Jon Wayne Parrott

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

[diff] [blame]

1520

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1521

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

1522

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

1523

# element.

1524

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

1525

"A String",

1526

],

1527

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1528

# side channel from client to backend.

1529

"A String",

1530

],

1531

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1532

# side channel from backend to client.

1533

"A String",

1534

],

1535

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

Jon Wayne Parrott

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

[diff] [blame]

1536

#

1537

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1538

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

1539

"A String",

1540

],

Jon Wayne Parrott

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

[diff] [blame]

1541

},

1542

],

1543

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1544

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

1545

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

1546

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

1547

# should be listed here by name. Example:

1548

#

1549

# enums:

1550

# - name: google.someapi.v1.SomeEnum

1551

{ # Enum type definition.

1552

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

1553

"enumvalue": [ # Enum value definitions.

1554

{ # Enum value definition.

1555

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

1556

"options": [ # Protocol buffer options.

1557

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

1558

# enumeration, etc.

1559

"value": { # The option's value packed in an Any message. If the value is a primitive,

1560

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1561

# should be used. If the value is an enum, it should be stored as an int32

1562

# value using the google.protobuf.Int32Value type.

1563

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

1564

},

1565

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1566

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1567

# For custom options, it should be the fully-qualified name. For example,

1568

# `"google.api.http"`.

1569

},

1570

],

1571

"number": 42, # Enum value number.

1572

},

1573

],

1574

"options": [ # Protocol buffer options.

1575

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

1576

# enumeration, etc.

1577

"value": { # The option's value packed in an Any message. If the value is a primitive,

1578

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1579

# should be used. If the value is an enum, it should be stored as an int32

1580

# value using the google.protobuf.Int32Value type.

1581

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

1582

},

1583

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1584

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1585

# For custom options, it should be the fully-qualified name. For example,

1586

# `"google.api.http"`.

1587

},

1588

],

1589

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

1590

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

1591

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

1592

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

1593

},

1594

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

1595

},

1596

],

1597

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

1598

# by the client for tracking purpose. Must be no longer than 63 characters

1599

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

1600

# empty, the server may choose to generate one instead.

1601

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

1602

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

1603

# service producer.

1604

#

1605

# Google Service Management currently only supports

1606

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

1607

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

1608

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

1609

# documented in https://cloud.google.com/pubsub/docs/overview.

1610

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

1611

#

1612

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

1613

{ # Usage configuration rules for the service.

1614

#

1615

# NOTE: Under development.

1616

#

1617

#

1618

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

1619

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

1620

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

1621

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

1622

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

1623

# allow/disallow unregistered calls.

1624

#

1625

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1631

#

1632

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

#

# usage:

# rules:

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

1637

# allow_unregistered_calls: true

1638

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

1639

# methods in all APIs.

1640

#

1641

# Refer to selector for syntax details.

1642

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

1643

# plane features, such as quota and billing, will not be available.

1644

# This flag is used by Google Cloud Endpoints to bypass checks for internal

1645

# methods, such as service health check methods.

1646

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

1647

# that don't identify any user or application.

1648

},

1649

],

1650

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

1651

#

1652

#

1653

# Use this field to configure per-product per-project service identity.

1654

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

1659

# display_name: "Cloud XXX Service Agent"

1660

# description: "Used as the identity of Cloud XXX to access resources"

1661

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

1662

#

1663

# An example name would be:

1664

# `projects/123456789`

1665

"displayName": "A String", # Optional. A user-specified name for the service account.

1666

# Must be less than or equal to 100 UTF-8 bytes.

1667

"description": "A String", # Optional. A user-specified opaque description of the service account.

1668

# Must be less than or equal to 256 UTF-8 bytes.

1669

},

1670

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

1671

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

1672

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

"A String",

],

},

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1677

{ # Defines a metric type and its schema. Once a metric descriptor is created,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1678

# deleting or altering it stops data collection and makes the metric type's

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1679

# existing data unusable.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1680

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

1681

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1682

# URL-encoded. All user-defined metric types have the DNS name

1683

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

1684

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1685

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1686

# "custom.googleapis.com/invoice/paid/amount"

1687

# "external.googleapis.com/prometheus/up"

1688

# "appengine.googleapis.com/http/server/response_latencies"

1689

"metadata": { # Additional annotations that can be used to guide the usage of a metric. # Optional. Metadata which can be used to guide usage of the metric.

1690

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

1691

# age are guaranteed to be ingested and available to be read, excluding

1692

# data loss due to errors.

1693

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

1694

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

1695

# periodically, consecutive data points are stored at this time interval,

1696

# excluding data loss due to errors. Metrics with a higher granularity have

1697

# a smaller sampling period.

1698

},

1699

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

1700

# Some combinations of `metric_kind` and `value_type` might not be supported.

1701

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

1702

# Some combinations of `metric_kind` and `value_type` might not be supported.

1703

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

1704

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

1705

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

1706

# This field is optional but it is recommended to be set for any metrics

1707

# associated with user-visible concepts, such as Quota.

1708

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1709

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

1710

# defines the representation of the stored metric values.

1711

#

1712

# Different systems may scale the values to be more easily displayed (so a

1713

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

1714

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

1715

# `KBy`, then the value of the metric is always in thousands of bytes, no

1716

# matter how it may be displayed..

1717

#

1718

# If you want a custom metric to record the exact number of CPU-seconds used

1719

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

1720

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

1721

# CPU-seconds, then the value is written as `12005`.

1722

#

1723

# Alternatively, if you want a custom metric to record data in a more

1724

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

1725

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

1726

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

1727

#

1728

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

Jon Wayne Parrott

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

[diff] [blame]

1729

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

1730

#

1731

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

1741

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

1749

# * `Y` yotta (10^24)

1750

#

1751

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

1752

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

1753

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

1754

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

1755

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

1756

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

1757

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

1758

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

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

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

[diff] [blame]

1765

#

1766

# **Grammar**

1767

#

Jon Wayne Parrott

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

[diff] [blame]

1768

# The grammar also includes these connectors:

1769

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1770

# * `/` division or ratio (as an infix operator). For examples,

1771

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

1772

# have `/s` in a metric `unit`; rates should always be computed at

1773

# query time from the underlying cumulative or delta value).

1774

# * `.` multiplication or composition (as an infix operator). For

1775

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

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

[diff] [blame]

1776

#

1777

# The grammar for a unit is as follows:

1778

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1779

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

Jon Wayne Parrott

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

[diff] [blame]

1780

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1781

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

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

[diff] [blame]

1782

# | Annotation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1783

# | "1"

Jon Wayne Parrott

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

[diff] [blame]

1784

# ;

1785

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1786

# Annotation = "{" NAME "}" ;

Jon Wayne Parrott

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

[diff] [blame]

1787

#

1788

# Notes:

1789

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1790

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

1791

# is used alone, then the unit is equivalent to `1`. For examples,

1792

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

Jon Wayne Parrott

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

[diff] [blame]

1793

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1794

# containing `{` or `}`.

1795

# * `1` represents a unitary [dimensionless

1796

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

1797

# as in `1/s`. It is typically used when none of the basic units are

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1798

# appropriate. For example, "new users per day" can be represented as

1799

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

1800

# users). Alternatively, "thousands of page views per day" would be

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1801

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1802

# value of `5.3` would mean "5300 page views per day").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1803

# * `%` represents dimensionless value of 1/100, and annotates values giving

1804

# a percentage (so the metric values are typically in the range of 0..100,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1805

# and a metric value `3` means "3 percent").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1806

# * `10^2.%` indicates a metric contains a ratio, typically in the range

1807

# 0..1, that will be multiplied by 100 and displayed as a percentage

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1808

# (so a metric value `0.03` means "3 percent").

1809

"monitoredResourceTypes": [ # Read-only. If present, then a time

1810

# series, which is identified partially by

1811

# a metric type and a MonitoredResourceDescriptor, that is associated

1812

# with this metric type can only be associated with one of the monitored

1813

# resource types listed here.

1814

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1815

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1816

"launchStage": "A String", # Optional. The launch stage of the metric definition.

1817

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

1818

# instance of this metric type. For example, the

1819

# `appengine.googleapis.com/http/server/response_latencies` metric

1820

# type has a label for the HTTP response code, `response_code`, so

1821

# you can look at latencies for successful responses or just

1822

# for responses that failed.

1823

{ # A description of a label.

1824

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

1825

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

1826

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

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1827

},

1828

],

Jon Wayne Parrott

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

[diff] [blame]

1829

},

1830

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1831

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

Jon Wayne Parrott

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

[diff] [blame]

1832

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1833

# Example for an API targeted for external use:

Jon Wayne Parrott

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

[diff] [blame]

1834

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1835

# name: calendar.googleapis.com

1836

# authentication:

1837

# providers:

1838

# - id: google_calendar_auth

1839

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

1840

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

Jon Wayne Parrott

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

[diff] [blame]

1841

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1842

# - selector: "*"

1843

# requirements:

1844

# provider_id: google_calendar_auth

1845

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

Jon Wayne Parrott

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

[diff] [blame]

1846

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1847

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

1848

{ # Authentication rules for the service.

1849

#

1850

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

1851

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

1852

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

1853

# request.

1854

#

1855

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

1856

# ignored.

1857

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

1858

{ # User-defined authentication requirements, including support for

1859

# [JSON Web Token

1860

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

1861

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

#

# Example:

#

# provider_id: bookstore_auth

1866

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

1867

# implemented and accepted in all the runtime components.

1868

#

1869

# The list of JWT

1870

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

1871

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

1872

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

1873

# "https://Service_name/API_name"

1874

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

1875

# LibraryService API will only accept JWTs with the following audience

1876

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1881

# bookstore_web.apps.googleusercontent.com

1882

},

Jon Wayne Parrott

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

[diff] [blame]

1883

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1884

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1885

#

1886

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1887

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

1888

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

1889

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

1890

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

1891

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

1892

#

1893

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

1894

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

1895

#

1896

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

1897

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

1898

# the OAuth scope across all of those APIs.

1899

#

1900

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

1901

# management about how developers will use them in practice.

1902

#

1903

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

1904

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

1905

# due to the backend requiring additional scopes or permissions.

1906

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

1907

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

#

# Example:

#

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

1912

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

},

},

],

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

1917

{ # Configuration for an authentication provider, including support for

1918

# [JSON Web Token

1919

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

1920

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

1921

# [OpenID

1922

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

1923

# Optional if the key set document:

1924

# - can be retrieved from

1925

# [OpenID

1926

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

1927

# the issuer.

1928

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

1929

# service account).

1930

#

1931

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

1932

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

1933

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

1934

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

1935

# be accepted. When this setting is absent, JWTs with audiences:

1936

# - "https://[service.name]/[google.protobuf.Api.name]"

1937

# - "https://[service.name]/"

1938

# will be accepted.

1939

# For example, if no audiences are in the setting, LibraryService API will

1940

# accept JWTs with the following audiences:

1941

# -

1942

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

1943

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1948

# bookstore_web.apps.googleusercontent.com

1949

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

1950

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

1951

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

1952

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

1953

# Usually a URL or an email address.

1954

#

1955

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

1956

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

1957

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

1958

# `AuthRequirement.provider_id`.

1959

#

1960

# Example: "bookstore_auth".

1961

"jwtLocations": [ # Defines the locations to extract the JWT.

1962

#

1963

# JWT locations can be either from HTTP headers or URL query parameters.

1964

# The rule is that the first match wins. The checking order is: checking

1965

# all headers first, then URL query parameters.

1966

#

1967

# If not specified, default to use following 3 locations:

1968

# 1) Authorization: Bearer

1969

# 2) x-goog-iap-jwt-assertion

1970

# 3) access_token query parameter

1971

#

1972

# Default locations can be specified as followings:

1973

# jwt_locations:

1974

# - header: Authorization

1975

# value_prefix: "Bearer "

1976

# - header: x-goog-iap-jwt-assertion

1977

# - query: access_token

1978

{ # Specifies a location to extract JWT from an API request.

1979

"header": "A String", # Specifies HTTP header name to extract JWT token.

1980

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

1981

# Only applies to "in" header type. Must be empty for "in" query type.

1982

# If not empty, the header value has to match (case sensitive) this prefix.

1983

# If not matched, JWT will not be extracted. If matched, JWT will be

1984

# extracted after the prefix is removed.

1985

#

1986

# For example, for "Authorization: Bearer {JWT}",

1987

# value_prefix="Bearer " with a space at the end.

1988

"query": "A String", # Specifies URL query parameter name to extract JWT token.

1989

},

1990

],

Jon Wayne Parrott

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

[diff] [blame]

1991

},

1992

],

1993

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1994

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

1995

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

1996

# monitoring, etc.

1997

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

1998

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

1999

},

2000

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

2001

# affects the interpretation of the service configuration. For example,

2002

# certain features are enabled by default for certain config versions.

2003

#

2004

# The latest config version is `3`.

Jon Wayne Parrott

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

[diff] [blame]

2005

}

2006

2007

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2014

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2015

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

2016

# describes basic information about a service, such as the name and the

2017

# title, and delegates other aspects to sub-sections. Each sub-section is

2018

# either a proto message or a repeated proto message that configures a

2019

# specific aspect, such as auth. See each proto message definition for details.

Jon Wayne Parrott

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

[diff] [blame]

#

# Example:

#

# type: google.api.Service

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2024

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

2025

# name: calendar.googleapis.com

2026

# title: Google Calendar API

2027

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2028

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2029

# authentication:

2030

# providers:

2031

# - id: google_calendar_auth

2032

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

2033

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

Jon Wayne Parrott

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

[diff] [blame]

2034

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2035

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2036

# requirements:

2037

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2038

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

Jon Wayne Parrott

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

[diff] [blame]

2039

#

2040

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

2041

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

2042

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

2043

# to both producer and consumer projects, whereas the

2044

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

2045

# consumer project.

2046

#

2047

# monitored_resources:

2048

# - type: library.googleapis.com/branch

2049

# labels:

2050

# - key: /city

2051

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

2052

# - key: /name

2053

# description: The name of the branch.

2054

# metrics:

2055

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2060

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2065

# monitoring:

2066

# producer_destinations:

2067

# - monitored_resource: library.googleapis.com/branch

2068

# metrics:

2069

# - library.googleapis.com/book/returned_count

2070

# consumer_destinations:

2071

# - monitored_resource: library.googleapis.com/branch

2072

# metrics:

2073

# - library.googleapis.com/book/returned_count

2074

# - library.googleapis.com/book/overdue_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2075

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2076

# There can be multiple consumer destinations. A monitored resouce type may

2077

# appear in multiple monitoring destinations if different aggregations are

2078

# needed for different sets of metrics associated with that monitored

2079

# resource type. A monitored resource and metric pair may only be used once

2080

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

2081

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

2082

# or the consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2083

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

Jon Wayne Parrott

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

[diff] [blame]

2084

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2085

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2086

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

"A String",

],

},

],

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

2092

# There can be multiple producer destinations. A monitored resouce type may

2093

# appear in multiple monitoring destinations if different aggregations are

2094

# needed for different sets of metrics associated with that monitored

2095

# resource type. A monitored resource and metric pair may only be used once

2096

# in the Monitoring configuration.

2097

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

2098

# or the consumer project).

2099

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

2100

# Service.monitored_resources section.

2101

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

2102

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

2103

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

],

},

],

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2108

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

2109

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

2110

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

2111

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

2112

# to define system APIs in ESF.

2113

{ # A protocol buffer message type.

2114

"options": [ # The protocol buffer options.

2115

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

2116

# enumeration, etc.

2117

"value": { # The option's value packed in an Any message. If the value is a primitive,

2118

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2119

# should be used. If the value is an enum, it should be stored as an int32

2120

# value using the google.protobuf.Int32Value type.

2121

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

2122

},

2123

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2124

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2125

# For custom options, it should be the fully-qualified name. For example,

2126

# `"google.api.http"`.

2127

},

2128

],

2129

"fields": [ # The list of fields.

2130

{ # A single field of a message type.

2131

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

2132

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

2133

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

2134

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

2135

"number": 42, # The field number.

2136

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

2137

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

2138

"options": [ # The protocol buffer options.

2139

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

2140

# enumeration, etc.

2141

"value": { # The option's value packed in an Any message. If the value is a primitive,

2142

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2143

# should be used. If the value is an enum, it should be stored as an int32

2144

# value using the google.protobuf.Int32Value type.

2145

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

2146

},

2147

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2148

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2149

# For custom options, it should be the fully-qualified name. For example,

2150

# `"google.api.http"`.

2151

},

2152

],

2153

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

2154

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

2155

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

2156

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

2157

},

2158

],

2159

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

2160

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

2161

"A String",

2162

],

2163

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

2164

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

2165

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

2166

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

2167

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

},

},

],

"producerProjectId": "A String", # The Google project that owns this service.

2172

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

2173

# usage.

2174

#

2175

# The metric based quota configuration works this way:

2176

# - The service configuration defines a set of metrics.

2177

# - For API calls, the quota.metric_rules maps methods to metrics with

2178

# corresponding costs.

2179

# - The quota.limits defines limits on the metrics, which will be used for

2180

# quota checks at runtime.

2181

#

2182

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

2188

# metric: library.googleapis.com/write_calls

2189

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

2195

# # except for the UpdateBook and DeleteBook methods. These two methods

2196

# # are mapped to the write_calls metric, with the UpdateBook method

2197

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

2202

# - selector: google.example.library.v1.LibraryService.UpdateBook

2203

# metric_costs:

2204

# library.googleapis.com/write_calls: 2

2205

# - selector: google.example.library.v1.LibraryService.DeleteBook

2206

# metric_costs:

2207

# library.googleapis.com/write_calls: 1

2208

#

2209

# Corresponding Metric definition:

2210

#

2211

# metrics:

2212

# - name: library.googleapis.com/read_calls

2213

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

2218

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

2223

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

2224

# for a limit type. There can be at most one limit for a duration and limit

2225

# type combination defined within a `QuotaGroup`.

2226

"name": "A String", # Name of the quota limit.

2227

#

2228

# The name must be provided, and it must be unique within the service. The

2229

# name can only include alphanumeric characters as well as '-'.

2230

#

2231

# The maximum length of the limit name is 64 characters.

2232

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

2233

# The free tier is the number of tokens that will be subtracted from the

2234

# billed amount when billing is enabled.

2235

# This field can only be set on a limit with duration "1d", in a billable

2236

# group; it is invalid on any other limit. If this field is not set, it

2237

# defaults to 0, indicating that there is no free tier for this service.

2238

#

2239

# Used by group-based quotas only.

2240

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

2241

#

2242

# Used by group-based quotas only.

2243

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

2244

# duration. This is the number of tokens assigned when a client

2245

# application developer activates the service for his/her project.

2246

#

2247

# Specifying a value of 0 will block all requests. This can be used if you

2248

# are provisioning quota to selected consumers and blocking others.

2249

# Similarly, a value of -1 will indicate an unlimited quota. No other

2250

# negative values are allowed.

2251

#

2252

# Used by group-based quotas only.

2253

"description": "A String", # Optional. User-visible, extended description for this quota limit.

2254

# Should be used only when more context is needed to understand this limit

2255

# than provided by the limit's display name (see: `display_name`).

2256

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

2257

# the same metric will be checked together during runtime. The metric must be

2258

# defined within the service config.

2259

"displayName": "A String", # User-visible display name for this limit.

2260

# Optional. If not set, the UI will provide a default display name based on

2261

# the quota configuration. This field can be used to override the default

2262

# display name generated from the configuration.

2263

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

2264

# integer value that is the maximum number of requests allowed for the

2265

# specified unit. Currently only STANDARD is supported.

2266

"a_key": "A String",

2267

},

2268

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

2269

# Metric.unit. The supported unit kinds are determined by the quota

2270

# backend system.

2271

#

2272

# Here are some examples:

2273

# * "1/min/{project}" for quota per minute per project.

2274

#

2275

# Note: the order of unit components is insignificant.

2276

# The "1" at the beginning is required to follow the metric unit syntax.

2277

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

2278

# duration. Client application developers can override the default limit up

2279

# to this maximum. If specified, this value cannot be set to a value less

2280

# than the default limit. If not specified, it is set to the default limit.

2281

#

2282

# To allow clients to apply overrides with no upper bound, set this to -1,

2283

# indicating unlimited maximum quota.

2284

#

2285

# Used by group-based quotas only.

2286

},

2287

],

2288

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

2289

# or more metrics.

2290

{ # Bind API methods to metrics. Binding a method to a metric causes that

2291

# metric's configured quota behaviors to apply to the method call.

2292

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

2293

#

2294

# Refer to selector for syntax details.

2295

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

2296

# cost applied to each metric.

2297

#

2298

# The key of the map is the metric name, and the values are the amount

2299

# increased for the metric against which the quota limits are defined.

2300

# The value must not be negative.

"a_key": "A String",

},

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

2307

# service, such as `calendar.googleapis.com`. The service name

2308

# typically goes through DNS verification to make sure the owner

2309

# of the service also owns the DNS name.

2310

"billing": { # Billing related configuration of the service. # Billing configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2311

#

2312

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2313

# for billing, `consumer_destinations` is the only supported destination and

2314

# the monitored resources need at least one label key

2315

# `cloud.googleapis.com/location` to indicate the location of the billing

2316

# usage, using different monitored resources between monitoring and billing is

2317

# recommended so they can be evolved independently:

2318

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2319

#

2320

# monitored_resources:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2321

# - type: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2322

# labels:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2323

# - key: cloud.googleapis.com/location

2324

# description: |

2325

# Predefined label to support billing location restriction.

2326

# - key: city

2327

# description: |

2328

# Custom label to define the city where the library branch is located

2329

# in.

2330

# - key: name

2331

# description: Custom label to define the name of the library branch.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2332

# metrics:

2333

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

2334

# metric_kind: DELTA

2335

# value_type: INT64

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2336

# unit: "1"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2337

# billing:

2338

# consumer_destinations:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2339

# - monitored_resource: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2340

# metrics:

2341

# - library.googleapis.com/book/borrowed_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2342

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2343

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

2344

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

2345

# one consumer destination.

2346

{ # Configuration of a specific billing destination (Currently only support

2347

# bill against consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2348

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2349

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2350

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

2351

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

2352

"A String",

2353

],

Jon Wayne Parrott

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

[diff] [blame]

2354

},

2355

],

2356

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2357

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

2358

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

2359

# error responses.

Jon Wayne Parrott

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

[diff] [blame]

2360

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2361

# Example:

Jon Wayne Parrott

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

[diff] [blame]

2362

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2363

# custom_error:

2364

# types:

2365

# - google.foo.v1.CustomError

2366

# - google.foo.v1.AnotherError

2367

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

Jon Wayne Parrott

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

[diff] [blame]

2368

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2369

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

2370

{ # A custom error rule.

2371

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

2372

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

2373

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

Jon Wayne Parrott

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

[diff] [blame]

2374

#

2375

# Refer to selector for syntax details.

2376

},

2377

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2378

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

2379

"A String",

Jon Wayne Parrott

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

[diff] [blame]

2380

],

2381

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2382

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

2383

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2384

# with the same name as the service is automatically generated to service all

2385

# defined APIs.

2386

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2387

# A service may expose any number of endpoints, and all endpoints share the

2388

# same service configuration, such as quota configuration and monitoring

2389

# configuration.

Jon Wayne Parrott

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

[diff] [blame]

2390

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2391

# Example service configuration:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2392

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2393

# name: library-example.googleapis.com

2394

# endpoints:

2395

# # Below entry makes 'google.example.library.v1.Library'

2396

# # API be served from endpoint address library-example.googleapis.com.

2397

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2398

# # it to decide whether the subsequent cross-origin request is

2399

# # allowed to proceed.

2400

# - name: library-example.googleapis.com

2401

# allow_cors: true

2402

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2403

# please specify multiple google.api.Endpoint for each of the intended

2404

# aliases.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2405

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2406

# Additional names that this endpoint will be hosted on.

2407

"A String",

2408

],

2409

"features": [ # The list of features enabled on this endpoint.

2410

"A String",

2411

],

2412

"allowCors": True or False, # Allowing

2413

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2414

# cross-domain traffic, would allow the backends served from this endpoint to

2415

# receive and respond to HTTP OPTIONS requests. The response will be used by

2416

# the browser to determine whether the subsequent cross-origin request is

2417

# allowed to proceed.

2418

"name": "A String", # The canonical name of this endpoint.

2419

"target": "A String", # The specification of an Internet routable address of API frontend that will

2420

# handle requests to this [API

2421

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

2422

# either a valid IPv4 address or a fully-qualified domain name. For example,

2423

# "8.8.8.8" or "myservice.appspot.com".

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2424

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2425

],

2426

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

2427

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2428

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2429

# - name: library.googleapis.com/activity_history

2430

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

2431

# display_name: Activity

2432

# labels:

2433

# - key: /customer_id

2434

# description: Identifier of a library customer

2435

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

2436

# Runtime requests that contain labels not specified here are

2437

# considered invalid.

2438

{ # A description of a label.

2439

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

2440

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

2441

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

2442

},

2443

],

2444

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

2445

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

2446

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

2447

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

2448

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

2449

# the documentation and can contain details.

2450

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

2451

# the user interface and should be concise.

2452

},

2453

],

2454

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

2455

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

2456

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

2457

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

2458

# which cannot be resolved against the associated IDL files.

2459

{ # Api is a light-weight descriptor for an API Interface.

2460

#

2461

# Interfaces are also described as "protocol buffer services" in some contexts,

2462

# such as by the "service" keyword in a .proto file, but they are different

2463

# from API Services, which represent a concrete implementation of an interface

2464

# as opposed to simply a description of methods and bindings. They are also

2465

# sometimes simply referred to as "APIs" in other contexts, such as the name of

2466

# this message itself. See https://cloud.google.com/apis/design/glossary for

2467

# detailed terminology.

2468

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

2469

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

2470

# enumeration, etc.

2471

"value": { # The option's value packed in an Any message. If the value is a primitive,

2472

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2473

# should be used. If the value is an enum, it should be stored as an int32

2474

# value using the google.protobuf.Int32Value type.

2475

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

2476

},

2477

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2478

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2479

# For custom options, it should be the fully-qualified name. For example,

2480

# `"google.api.http"`.

2481

},

2482

],

2483

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

2484

{ # Method represents a method of an API interface.

2485

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

2486

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

2487

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

2488

# enumeration, etc.

2489

"value": { # The option's value packed in an Any message. If the value is a primitive,

2490

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2491

# should be used. If the value is an enum, it should be stored as an int32

2492

# value using the google.protobuf.Int32Value type.

2493

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

2494

},

2495

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2496

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2497

# For custom options, it should be the fully-qualified name. For example,

2498

# `"google.api.http"`.

2499

},

2500

],

2501

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

2502

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

2503

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

2504

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

2505

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

2506

},

2507

],

2508

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

2509

# followed by the interface's simple name.

2510

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

2511

# message.

2512

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

2513

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

2514

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

2515

},

2516

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

2517

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

2518

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

2519

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

2520

# major version is derived from the package name, as outlined below. If the

2521

# field is not empty, the version in the package name will be verified to be

2522

# consistent with what is provided here.

2523

#

2524

# The versioning schema uses [semantic

2525

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

2526

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

2527

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

2528

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

2529

# chosen based on the product plan.

2530

#

2531

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

2532

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

2533

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

2534

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

2535

# experimental, non-GA interfaces.

2536

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

2537

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

2538

# interface must redeclare all the methods from the included interface, but

2539

# documentation and options are inherited as follows:

2540

#

2541

# - If after comment and whitespace stripping, the documentation

2542

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

2543

# from the original method.

2544

#

2545

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

2546

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

2547

# inherited.

2548

#

2549

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

2550

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

2551

# version of the including interface plus the root path if

2552

# specified.

2553

#

2554

# Example of a simple mixin:

2555

#

2556

# package google.acl.v1;

2557

# service AccessControl {

2558

# // Get the underlying ACL object.

2559

# rpc GetAcl(GetAclRequest) returns (Acl) {

2560

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

# }

# }

#

# package google.storage.v2;

2565

# service Storage {

2566

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

2567

#

2568

# // Get a data record.

2569

# rpc GetData(GetDataRequest) returns (Data) {

2570

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

# }

# }

#

# Example of a mixin configuration:

2575

#

2576

# apis:

2577

# - name: google.storage.v2.Storage

2578

# mixins:

2579

# - name: google.acl.v1.AccessControl

2580

#

2581

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

2582

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

2583

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

2584

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

2585

# documentation and annotations as follows:

2586

#

2587

# service Storage {

2588

# // Get the underlying ACL object.

2589

# rpc GetAcl(GetAclRequest) returns (Acl) {

2590

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

# }

# ...

# }

#

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

2596

#

2597

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

2598

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

2599

#

2600

# apis:

2601

# - name: google.storage.v2.Storage

2602

# mixins:

2603

# - name: google.acl.v1.AccessControl

2604

# root: acls

2605

#

2606

# This implies the following inherited HTTP annotation:

2607

#

2608

# service Storage {

2609

# // Get the underlying ACL object.

2610

# rpc GetAcl(GetAclRequest) returns (Acl) {

2611

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

# }

# ...

# }

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

2616

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

# are rooted.

},

],

},

],

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

2623

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

2624

# automatically included. Messages which are not referenced but

2625

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

2626

# should be listed here by name. Example:

2627

#

2628

# types:

2629

# - name: google.protobuf.Int32

2630

{ # A protocol buffer message type.

2631

"options": [ # The protocol buffer options.

2632

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

2633

# enumeration, etc.

2634

"value": { # The option's value packed in an Any message. If the value is a primitive,

2635

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2636

# should be used. If the value is an enum, it should be stored as an int32

2637

# value using the google.protobuf.Int32Value type.

2638

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

2639

},

2640

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2641

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2642

# For custom options, it should be the fully-qualified name. For example,

2643

# `"google.api.http"`.

2644

},

2645

],

2646

"fields": [ # The list of fields.

2647

{ # A single field of a message type.

2648

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

2649

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

2650

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

2651

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

2652

"number": 42, # The field number.

2653

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

2654

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

2655

"options": [ # The protocol buffer options.

2656

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

2657

# enumeration, etc.

2658

"value": { # The option's value packed in an Any message. If the value is a primitive,

2659

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2660

# should be used. If the value is an enum, it should be stored as an int32

2661

# value using the google.protobuf.Int32Value type.

2662

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

2663

},

2664

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2665

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2666

# For custom options, it should be the fully-qualified name. For example,

2667

# `"google.api.http"`.

2668

},

2669

],

2670

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

2671

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

2672

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

2673

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

2674

},

2675

],

2676

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

2677

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

2678

"A String",

2679

],

2680

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

2681

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

2682

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

2683

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

2684

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

},

},

],

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

2689

"sourceFiles": [ # All files used during config generation.

2690

{

2691

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

2692

},

Jon Wayne Parrott

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

[diff] [blame]

2693

],

2694

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2695

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

Jon Wayne Parrott

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

[diff] [blame]

2696

# HttpRule, each specifying the mapping of an RPC method

2697

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2698

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

2699

# cases of single segment matches in reserved expansion, where "%2F" will be

2700

# left encoded.

Jon Wayne Parrott

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

[diff] [blame]

2701

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2702

# The default behavior is to not decode RFC 6570 reserved characters in multi

2703

# segment matches.

2704

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

2705

#

2706

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2707

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

2708

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2709

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

2710

# more HTTP REST endpoints. It allows developers to build a single API service

2711

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

2712

# APIs](https://github.com/googleapis/googleapis),

2713

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

2714

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

2715

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

2716

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

2717

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2718

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

2719

# how different portions of the gRPC request message are mapped to the URL

2720

# path, URL query parameters, and HTTP request body. It also controls how the

2721

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

2722

# typically specified as an `google.api.http` annotation on the gRPC method.

2723

#

2724

# Each mapping specifies a URL path template and an HTTP method. The path

2725

# template may refer to one or more fields in the gRPC request message, as long

2726

# as each field is a non-repeated field with a primitive (non-message) type.

2727

# The path template controls how fields of the request message are mapped to

2728

# the URL path.

2729

#

2730

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2731

#

2732

# service Messaging {

2733

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2734

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2735

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2736

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2737

# }

2738

# }

2739

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2740

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2741

# }

2742

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2743

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2744

# }

2745

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2746

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2747

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2748

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

2749

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2750

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

Jon Wayne Parrott

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

[diff] [blame]

2751

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2752

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

2753

# automatically become HTTP query parameters if there is no HTTP request body.

2754

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2755

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2756

# service Messaging {

2757

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2758

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2759

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2760

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2761

# }

2762

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2763

# message GetMessageRequest {

2764

# message SubMessage {

2765

# string subfield = 1;

2766

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2767

# string message_id = 1; // Mapped to URL path.

2768

# int64 revision = 2; // Mapped to URL query parameter `revision`.

2769

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2770

# }

2771

#

Jon Wayne Parrott

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

[diff] [blame]

2772

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

2773

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2774

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

2775

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2776

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2777

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

2778

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

2779

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2780

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

2781

# primitive type or a repeated primitive type or a non-repeated message type.

2782

# In the case of a repeated type, the parameter can be repeated in the URL

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2783

# as `...?param=A&param=B`. In the case of a message type, each field of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2784

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2785

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

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

[diff] [blame]

2786

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2787

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

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

[diff] [blame]

2788

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

2789

# message resource collection:

2790

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2791

# service Messaging {

2792

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2793

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2794

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

2795

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

2800

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

2801

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

2802

# }

2803

#

Jon Wayne Parrott

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

[diff] [blame]

2804

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

2805

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

2806

# protos JSON encoding:

2807

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2808

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

2809

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2810

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

2811

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

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

[diff] [blame]

2812

#

2813

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

2814

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

2815

# request body. This enables the following alternative definition of

2816

# the update method:

2817

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2818

# service Messaging {

2819

# rpc UpdateMessage(Message) returns (Message) {

2820

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2821

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

2822

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

2828

# string text = 2;

2829

# }

2830

#

Jon Wayne Parrott

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

[diff] [blame]

2831

#

2832

# The following HTTP JSON to RPC mapping is enabled:

2833

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2834

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

2835

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2836

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

2837

# "123456" text: "Hi!")`

Jon Wayne Parrott

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

[diff] [blame]

2838

#

2839

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

2840

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

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2841

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

Jon Wayne Parrott

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

[diff] [blame]

2842

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2843

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

Jon Wayne Parrott

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

[diff] [blame]

2844

#

2845

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

2846

# the `additional_bindings` option. Example:

2847

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2848

# service Messaging {

2849

# rpc GetMessage(GetMessageRequest) returns (Message) {

2850

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2851

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2852

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2853

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2854

# }

2855

# };

Jon Wayne Parrott

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

[diff] [blame]

2856

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2857

# }

2858

# message GetMessageRequest {

2859

# string message_id = 1;

2860

# string user_id = 2;

2861

# }

2862

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2863

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

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

[diff] [blame]

2864

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2865

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

2866

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

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2867

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

2868

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

2869

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

2870

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2871

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

2872

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2873

# 1. Leaf request fields (recursive expansion nested messages in the request

2874

# message) are classified into three categories:

2875

# - Fields referred by the path template. They are passed via the URL path.

2876

# - Fields referred by the HttpRule.body. They are passed via the HTTP

2877

# request body.

2878

# - All other fields are passed via the URL query parameters, and the

2879

# parameter name is the field path in the request message. A repeated

2880

# field can be represented as multiple query parameters under the same

2881

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2882

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2883

# are passed via URL path and HTTP request body.

2884

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

2885

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

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

[diff] [blame]

2886

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2887

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

2888

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2889

# Template = "/" Segments [ Verb ] ;

2890

# Segments = Segment { "/" Segment } ;

2891

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

2892

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

2893

# FieldPath = IDENT { "." IDENT } ;

2894

# Verb = ":" LITERAL ;

Jon Wayne Parrott

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

[diff] [blame]

2895

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2896

# The syntax `*` matches a single URL path segment. The syntax `**` matches

2897

# zero or more URL path segments, which must be the last part of the URL path

2898

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

2899

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2900

# The syntax `Variable` matches part of the URL path as specified by its

2901

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

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

[diff] [blame]

2902

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

2903

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

2904

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2905

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

2906

# contains any reserved character, such characters should be percent-encoded

2907

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

2908

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2909

# If a variable contains exactly one path segment, such as `"{var}"` or

2910

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2911

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

2912

# server side does the reverse decoding. Such variables show up in the

2913

# [Discovery

2914

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2915

# `{var}`.

2916

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2917

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

2918

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2919

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2920

# The server side does the reverse decoding, except "%2F" and "%2f" are left

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2921

# unchanged. Such variables show up in the

2922

# [Discovery

2923

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2924

# `{+var}`.

2925

#

2926

# ## Using gRPC API Service Configuration

2927

#

2928

# gRPC API Service Configuration (service config) is a configuration language

2929

# for configuring a gRPC service to become a user-facing product. The

2930

# service config is simply the YAML representation of the `google.api.Service`

2931

# proto message.

2932

#

2933

# As an alternative to annotating your proto file, you can configure gRPC

2934

# transcoding in your service config YAML files. You do this by specifying a

2935

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

2936

# effect as the proto annotation. This can be particularly useful if you

2937

# have a proto that is reused in multiple services. Note that any transcoding

2938

# specified in the service config will override any matching transcoding

2939

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

2946

# - selector: example.v1.Messaging.GetMessage

2947

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

2952

# proto to JSON conversion must follow the [proto3

2953

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

2954

#

2955

# While the single segment variable follows the semantics of

2956

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

2957

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

2958

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

2959

# does not expand special characters like `?` and `#`, which would lead

2960

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

2961

# for multi segment variables.

2962

#

2963

# The path variables **must not** refer to any repeated or mapped field,

2964

# because client libraries are not capable of handling such variable expansion.

2965

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2966

# The path variables **must not** capture the leading "/" character. The reason

2967

# is that the most common use case "{var}" does not capture the leading "/"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2968

# character. For consistency, all path variables must share the same behavior.

2969

#

2970

# Repeated message fields must not be mapped to URL query parameters, because

2971

# no client library can support such complicated mapping.

2972

#

2973

# If an API needs to use a JSON array for request or response body, it can map

2974

# the request or response body to a repeated field. However, some gRPC

2975

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2976

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

2977

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

Jon Wayne Parrott

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

[diff] [blame]

2978

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

2979

# the nesting may only be one level deep).

2980

# Object with schema name: HttpRule

2981

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2982

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

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2983

# response body. When omitted, the entire response message will be used

2984

# as the HTTP response body.

2985

#

2986

# NOTE: The referred field must be present at the top-level of the response

2987

# message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2988

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

2989

# body, or `*` for mapping all request fields not captured by the path

2990

# pattern to the HTTP body, or omitted for not having any HTTP request body.

2991

#

2992

# NOTE: the referred field must be present at the top-level of the request

2993

# message type.

2994

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

2995

#

2996

# Refer to selector for syntax details.

2997

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

2998

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

2999

# included in the `pattern` field, such as HEAD, or "*" to leave the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3000

# HTTP method unspecified for this rule. The wild-card rule is useful

3001

# for services that provide content to Web (HTML) clients.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3002

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

3003

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

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3004

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3005

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

3006

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

3007

# resources.

3008

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

3009

# half-duplex streaming method.

3010

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Jon Wayne Parrott

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

[diff] [blame]

3011

},

3012

],

3013

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3014

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3015

#

3016

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

3017

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

3018

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

3019

# change the names of the system parameters.

3020

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3021

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3022

# The parameters defined here will override the default parameters

3023

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

3024

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

3025

# and names is implementation-dependent.

3026

#

3027

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3035

#

3036

#

3037

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3042

# parameters:

3043

# - name: api_key

3044

# http_header: Api-Key1

3045

# - name: api_key

3046

# http_header: Api-Key2

3047

#

3048

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

3049

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

3050

# methods.

3051

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

3052

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

3053

# names are used the behavior is implementation-dependent.

3054

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

3055

# parameter-dependent.

3056

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

3057

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

3058

# is implementation-dependent.

3059

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

3060

# insensitive.

3061

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3062

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

3063

# sensitive.

Jon Wayne Parrott

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

[diff] [blame]

3064

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3065

],

3066

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

3067

# methods in all APIs.

3068

#

3069

# Refer to selector for syntax details.

},

],

},

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

3074

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

3075

#

3076

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

3077

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

3078

"protocol": "A String", # The protocol used for sending a request to the backend.

3079

# The supported values are "http/1.1" and "h2".

3080

#

3081

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

3091

# to "h2" for improved performance.

3092

#

3093

# Configuring this field to non-default values is only supported for secure

3094

# HTTP backends. This field will be ignored for all other backends.

3095

#

3096

# See

3097

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

3098

# for more details on the supported values.

3099

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

3100

#

3101

# Refer to selector for syntax details.

3102

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

3103

# operation. The default is no deadline.

3104

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

3105

# varies based on the request protocol and deployment environment.

3106

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

3107

# value lower than this will be rejected.

3108

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

3109

#

3110

# The scheme is used to determine the backend protocol and security.

3111

# The following schemes are accepted:

3112

#

3113

# SCHEME PROTOCOL SECURITY

# http:// HTTP None

# https:// HTTP TLS

# grpc:// gRPC None

# grpcs:// gRPC TLS

#

# It is recommended to explicitly include a scheme. Leaving out the scheme

3120

# may cause constrasting behaviors across platforms.

3121

#

3122

# If the port is unspecified, the default is:

3123

# - 80 for schemes without TLS

3124

# - 443 for schemes with TLS

3125

#

3126

# For HTTP backends, use protocol

3127

# to specify the protocol version.

3128

"pathTranslation": "A String",

3129

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

3130

# This ID token will be added in the HTTP "authorization" header, and sent

3131

# to the backend.

3132

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

3133

# original "Authorization" HTTP header will be preserved. If the header is

3134

# used to carry the original token and is expected by the backend, this

3135

# field must be set to true to preserve the header.

3136

"renameTo": "A String", # Unimplemented. Do not use.

3137

#

3138

# The new name the selected proto elements should be renamed to.

3139

#

3140

# The package, the service and the method can all be renamed.

3141

# The backend server should implement the renamed proto. However, clients

3142

# should call the original method, and ESF routes the traffic to the renamed

3143

# method.

3144

#

3145

# HTTP clients should call the URL mapped to the original method.

3146

# gRPC and Stubby clients should call the original method with package name.

3147

#

3148

# For legacy reasons, ESF allows Stubby clients to call with the

3149

# short name (without the package name). However, for API Versioning(or

3150

# multiple methods mapped to the same short name), all Stubby clients must

3151

# call the method's full name with the package name, otherwise the first one

3152

# (selector) wins.

3153

#

3154

# If this `rename_to` is specified with a trailing `*`, the `selector` must

3155

# be specified with a trailing `*` as well. The all element short names

3156

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

3162

# rename_to: google.example.library.*

3163

#

3164

# The selector matches `google.example.library.v1.Library.CreateShelf` and

3165

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

3166

# `google.example.library.Library.CreateShelf` and

3167

# `google.example.library.Library.CreateBook`. It essentially renames the

3168

# proto package name section of the matched proto service and methods.

},

],

},

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

3173

#

3174

# Example:

3175

# <pre><code>documentation:

3176

# summary: >

3177

# The Google Calendar API gives access

3178

# to most calendar features.

3179

# pages:

3180

# - name: Overview

3181

# content: &#40;== include google/foo/overview.md ==&#41;

3182

# - name: Tutorial

3183

# content: &#40;== include google/foo/tutorial.md ==&#41;

3184

# subpages;

3185

# - name: Java

3186

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

3187

# rules:

3188

# - selector: google.calendar.Calendar.Get

3189

# description: >

3190

# ...

3191

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3196

# standard markdown features, definition lists, tables and fenced

3197

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

3198

# interpreted relative to the section nesting of the context where

3199

# a documentation fragment is embedded.

3200

#

3201

# Documentation from the IDL is merged with documentation defined

3202

# via the config at normalization time, where documentation provided

3203

# by config rules overrides IDL provided.

3204

#

3205

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

3206

# in documentation text.

3207

#

3208

# In order to reference a proto element, the following

3209

# notation can be used:

3210

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

3211

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

3212

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

3213

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

3214

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

3215

#

3216

# A few directives are available in documentation. Note that

3217

# directives must appear on a single line to be properly

3218

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

3219

# an external source:

3220

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

3221

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

3222

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

3223

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

3224

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

3225

# The directive `suppress_warning` does not directly affect documentation

3226

# and is documented together with service config validation.

3227

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

3228

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

3229

#

3230

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

3231

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

3232

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

3233

# an element is marked as `deprecated`.

3234

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

3235

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

3236

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

3237

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

3238

# wildcard will match one or more components. To specify a default for all

3239

# applicable elements, the whole pattern "*" is used.

3240

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

3241

},

3242

],

3243

"summary": "A String", # A short summary of what the service does. Can only be provided by

3244

# plain text.

3245

"overview": "A String", # Declares a single overview page. For example:

3246

# <pre><code>documentation:

3247

# summary: ...

3248

# overview: &#40;== include overview.md ==&#41;

3249

# </code></pre>

3250

# This is a shortcut for the following declaration (using pages style):

3251

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

3256

# </code></pre>

3257

# Note: you cannot specify both `overview` field and `pages` field.

3258

"pages": [ # The top level pages for the documentation set.

3259

{ # Represents a documentation page. A page can contain subpages to represent

3260

# nested documentation set structure.

3261

"name": "A String", # The name of the page. It will be used as an identity of the page to

3262

# generate URI of the page, text of the link to this page in navigation,

3263

# etc. The full page name (start from the root page name to this page

3264

# concatenated with `.`) can be used as reference to the page in your

3265

# documentation. For example:

3266

# <pre><code>pages:

3267

# - name: Tutorial

3268

# content: &#40;== include tutorial.md ==&#41;

3269

# subpages:

3270

# - name: Java

3271

# content: &#40;== include tutorial_java.md ==&#41;

3272

# </code></pre>

3273

# You can reference `Java` page using Markdown reference link syntax:

3274

# `Java`.

3275

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

3276

# ==&#41;</code> to include content from a Markdown file.

3277

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3278

# honored in the generated docset.

3279

# Object with schema name: Page

],

},

],

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

3284

# from the yaml file) is not suitable. This can be seen in any fully

3285

# specified service urls as well as sections that show a base that other

3286

# urls are relative to.

3287

},

3288

"logging": { # Logging configuration of the service. # Logging configuration.

3289

#

3290

# The following example shows how to configure logs to be sent to the

3291

# producer and consumer projects. In the example, the `activity_history`

3292

# log is sent to both the producer and consumer projects, whereas the

3293

# `purchase_history` log is only sent to the producer project.

3294

#

3295

# monitored_resources:

3296

# - type: library.googleapis.com/branch

3297

# labels:

3298

# - key: /city

3299

# description: The city where the library branch is located in.

3300

# - key: /name

3301

# description: The name of the branch.

3302

# logs:

3303

# - name: activity_history

3304

# labels:

3305

# - key: /customer_id

3306

# - name: purchase_history

3307

# logging:

3308

# producer_destinations:

3309

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

3314

# - monitored_resource: library.googleapis.com/branch

3315

# logs:

3316

# - activity_history

3317

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3318

# There can be multiple producer destinations, each one must have a

3319

# different monitored resource type. A log can be used in at most

3320

# one producer destination.

3321

{ # Configuration of a specific logging destination (the producer project

3322

# or the consumer project).

3323

"logs": [ # Names of the logs to be sent to this destination. Each name must

3324

# be defined in the Service.logs section. If the log name is

3325

# not a domain scoped name, it will be automatically prefixed with

3326

# the service name followed by "/".

3327

"A String",

3328

],

3329

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

3330

# Service.monitored_resources section.

3331

},

3332

],

3333

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

3334

# There can be multiple consumer destinations, each one must have a

3335

# different monitored resource type. A log can be used in at most

3336

# one consumer destination.

3337

{ # Configuration of a specific logging destination (the producer project

3338

# or the consumer project).

3339

"logs": [ # Names of the logs to be sent to this destination. Each name must

3340

# be defined in the Service.logs section. If the log name is

3341

# not a domain scoped name, it will be automatically prefixed with

3342

# the service name followed by "/".

3343

"A String",

3344

],

3345

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

3346

# Service.monitored_resources section.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3351

# by the Service.monitoring and Service.logging configurations.

3352

{ # An object that describes the schema of a MonitoredResource object using a

3353

# type name and a set of labels. For example, the monitored resource

3354

# descriptor for Google Compute Engine VM instances has a type of

3355

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3356

# `"zone"` to identify particular VM instances.

3357

#

3358

# Different APIs can support different monitored resource types. APIs generally

3359

# provide a `list` method that returns the monitored resource descriptors used

3360

# by the API.

3361

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3362

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3363

# without any article or other determiners. For example,

3364

# `"Google Cloud SQL Database"`.

3365

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3366

# be used in documentation.

3367

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

3368

"labels": [ # Required. A set of labels used to describe instances of this monitored

3369

# resource type. For example, an individual Google Cloud SQL database is

3370

# identified by values for the labels `"database_id"` and `"zone"`.

3371

{ # A description of a label.

3372

"key": "A String", # The label key.

3373

"description": "A String", # A human-readable description for the label.

3374

"valueType": "A String", # The type of data that can be assigned to the label.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3375

},

3376

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3377

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3378

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3379

# {type} is the value of the `type` field in this object and

3380

# {project_id} is a project ID that provides API-specific context for

3381

# accessing the type. APIs that do not use project information can use the

3382

# resource name format `"monitoredResourceDescriptors/{type}"`.

3383

"type": "A String", # Required. The monitored resource type. For example, the type

3384

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3385

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3386

},

3387

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3388

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3389

#

3390

# Example:

3391

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

3397

# - google.rpc.context.OriginContext

3398

#

3399

# The above specifies that all methods in the API request

3400

# `google.rpc.context.ProjectContext` and

3401

# `google.rpc.context.OriginContext`.

3402

#

3403

# Available context types are defined in package

3404

# `google.rpc.context`.

3405

#

3406

# This also provides mechanism to whitelist any protobuf message extension that

3407

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

3408

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

3409

# specific protobuf types that can appear in grpc metadata as follows in your

# yaml file:

#

# Example:

#

# context:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3417

# allowed_request_extensions:

3418

# - google.foo.v1.NewExtension

3419

# allowed_response_extensions:

3420

# - google.foo.v1.NewExtension

3421

#

3422

# You can also specify extension ID instead of fully qualified extension name

3423

# here.

3424

"rules": [ # A list of RPC context rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3425

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3426

# **NOTE:** All service configuration rules follow "last one wins" order.

3427

{ # A context rule provides information about the context for an individual API

3428

# element.

3429

"requested": [ # A list of full type names of requested contexts.

3430

"A String",

3431

],

3432

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3433

# side channel from client to backend.

3434

"A String",

3435

],

3436

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3437

# side channel from backend to client.

3438

"A String",

3439

],

3440

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3441

#

3442

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3443

"provided": [ # A list of full type names of provided contexts.

3444

"A String",

3445

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3446

},

3447

],

3448

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3449

"enums": [ # A list of all enum types included in this API service. Enums

3450

# referenced directly or indirectly by the `apis` are automatically

3451

# included. Enums which are not referenced but shall be included

3452

# should be listed here by name. Example:

3453

#

3454

# enums:

3455

# - name: google.someapi.v1.SomeEnum

3456

{ # Enum type definition.

3457

"name": "A String", # Enum type name.

3458

"enumvalue": [ # Enum value definitions.

3459

{ # Enum value definition.

3460

"name": "A String", # Enum value name.

3461

"options": [ # Protocol buffer options.

3462

{ # A protocol buffer option, which can be attached to a message, field,

3463

# enumeration, etc.

3464

"value": { # The option's value packed in an Any message. If the value is a primitive,

3465

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3466

# should be used. If the value is an enum, it should be stored as an int32

3467

# value using the google.protobuf.Int32Value type.

3468

"a_key": "", # Properties of the object. Contains field @type with type URL.

3469

},

3470

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3471

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3472

# For custom options, it should be the fully-qualified name. For example,

3473

# `"google.api.http"`.

3474

},

3475

],

3476

"number": 42, # Enum value number.

3477

},

3478

],

3479

"options": [ # Protocol buffer options.

3480

{ # A protocol buffer option, which can be attached to a message, field,

3481

# enumeration, etc.

3482

"value": { # The option's value packed in an Any message. If the value is a primitive,

3483

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3484

# should be used. If the value is an enum, it should be stored as an int32

3485

# value using the google.protobuf.Int32Value type.

3486

"a_key": "", # Properties of the object. Contains field @type with type URL.

3487

},

3488

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3489

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3490

# For custom options, it should be the fully-qualified name. For example,

3491

# `"google.api.http"`.

3492

},

3493

],

3494

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3495

# protobuf element, like the file in which it is defined.

3496

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3497

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3498

},

3499

"syntax": "A String", # The source syntax.

3500

},

3501

],

3502

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3503

# by the client for tracking purpose. Must be no longer than 63 characters

3504

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

3505

# empty, the server may choose to generate one instead.

3506

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3507

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

3508

# service producer.

3509

#

3510

# Google Service Management currently only supports

3511

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

3512

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

3513

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

3514

# documented in https://cloud.google.com/pubsub/docs/overview.

3515

"rules": [ # A list of usage rules that apply to individual API methods.

3516

#

3517

# **NOTE:** All service configuration rules follow "last one wins" order.

3518

{ # Usage configuration rules for the service.

3519

#

3520

# NOTE: Under development.

3521

#

3522

#

3523

# Use this rule to configure unregistered calls for the service. Unregistered

3524

# calls are calls that do not contain consumer project identity.

3525

# (Example: calls that do not contain an API key).

3526

# By default, API methods do not allow unregistered calls, and each method call

3527

# must be identified by a consumer project identity. Use this rule to

3528

# allow/disallow unregistered calls.

3529

#

3530

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3536

#

3537

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3542

# allow_unregistered_calls: true

3543

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3544

# methods in all APIs.

3545

#

3546

# Refer to selector for syntax details.

3547

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

3548

# plane features, such as quota and billing, will not be available.

3549

# This flag is used by Google Cloud Endpoints to bypass checks for internal

3550

# methods, such as service health check methods.

3551

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

3552

# that don't identify any user or application.

3553

},

3554

],

3555

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

3556

#

3557

#

3558

# Use this field to configure per-product per-project service identity.

3559

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

3564

# display_name: "Cloud XXX Service Agent"

3565

# description: "Used as the identity of Cloud XXX to access resources"

3566

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

3567

#

3568

# An example name would be:

3569

# `projects/123456789`

3570

"displayName": "A String", # Optional. A user-specified name for the service account.

3571

# Must be less than or equal to 100 UTF-8 bytes.

3572

"description": "A String", # Optional. A user-specified opaque description of the service account.

3573

# Must be less than or equal to 256 UTF-8 bytes.

3574

},

3575

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3576

# service. Each requirement is of the form <service.name>/<requirement-id>;

3577

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3582

{ # Defines a metric type and its schema. Once a metric descriptor is created,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3583

# deleting or altering it stops data collection and makes the metric type's

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3584

# existing data unusable.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3585

"name": "A String", # The resource name of the metric descriptor.

3586

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3587

# URL-encoded. All user-defined metric types have the DNS name

3588

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

3589

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3590

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3591

# "custom.googleapis.com/invoice/paid/amount"

3592

# "external.googleapis.com/prometheus/up"

3593

# "appengine.googleapis.com/http/server/response_latencies"

3594

"metadata": { # Additional annotations that can be used to guide the usage of a metric. # Optional. Metadata which can be used to guide usage of the metric.

3595

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

3596

# age are guaranteed to be ingested and available to be read, excluding

3597

# data loss due to errors.

3598

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

3599

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

3600

# periodically, consecutive data points are stored at this time interval,

3601

# excluding data loss due to errors. Metrics with a higher granularity have

3602

# a smaller sampling period.

3603

},

3604

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

3605

# Some combinations of `metric_kind` and `value_type` might not be supported.

3606

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

3607

# Some combinations of `metric_kind` and `value_type` might not be supported.

3608

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3609

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3610

# Use sentence case without an ending period, for example "Request count".

3611

# This field is optional but it is recommended to be set for any metrics

3612

# associated with user-visible concepts, such as Quota.

3613

"unit": "A String", # The units in which the metric value is reported. It is only applicable

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3614

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

3615

# defines the representation of the stored metric values.

3616

#

3617

# Different systems may scale the values to be more easily displayed (so a

3618

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

3619

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

3620

# `KBy`, then the value of the metric is always in thousands of bytes, no

3621

# matter how it may be displayed..

3622

#

3623

# If you want a custom metric to record the exact number of CPU-seconds used

3624

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

3625

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

3626

# CPU-seconds, then the value is written as `12005`.

3627

#

3628

# Alternatively, if you want a custom metric to record data in a more

3629

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

3630

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

3631

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

3632

#

3633

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3634

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3635

#

3636

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

3646

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

3654

# * `Y` yotta (10^24)

3655

#

3656

# * `m` milli (10^-3)

3657

# * `u` micro (10^-6)

3658

# * `n` nano (10^-9)

3659

# * `p` pico (10^-12)

3660

# * `f` femto (10^-15)

3661

# * `a` atto (10^-18)

3662

# * `z` zepto (10^-21)

3663

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3670

#

3671

# **Grammar**

3672

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3673

# The grammar also includes these connectors:

3674

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3675

# * `/` division or ratio (as an infix operator). For examples,

3676

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

3677

# have `/s` in a metric `unit`; rates should always be computed at

3678

# query time from the underlying cumulative or delta value).

3679

# * `.` multiplication or composition (as an infix operator). For

3680

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3681

#

3682

# The grammar for a unit is as follows:

3683

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3684

# Expression = Component { "." Component } { "/" Component } ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3685

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3686

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3687

# | Annotation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3688

# | "1"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3689

# ;

3690

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3691

# Annotation = "{" NAME "}" ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3692

#

3693

# Notes:

3694

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3695

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

3696

# is used alone, then the unit is equivalent to `1`. For examples,

3697

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3698

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3699

# containing `{` or `}`.

3700

# * `1` represents a unitary [dimensionless

3701

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

3702

# as in `1/s`. It is typically used when none of the basic units are

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3703

# appropriate. For example, "new users per day" can be represented as

3704

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

3705

# users). Alternatively, "thousands of page views per day" would be

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3706

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3707

# value of `5.3` would mean "5300 page views per day").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3708

# * `%` represents dimensionless value of 1/100, and annotates values giving

3709

# a percentage (so the metric values are typically in the range of 0..100,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3710

# and a metric value `3` means "3 percent").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3711

# * `10^2.%` indicates a metric contains a ratio, typically in the range

3712

# 0..1, that will be multiplied by 100 and displayed as a percentage

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3713

# (so a metric value `0.03` means "3 percent").

3714

"monitoredResourceTypes": [ # Read-only. If present, then a time

3715

# series, which is identified partially by

3716

# a metric type and a MonitoredResourceDescriptor, that is associated

3717

# with this metric type can only be associated with one of the monitored

3718

# resource types listed here.

3719

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3720

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3721

"launchStage": "A String", # Optional. The launch stage of the metric definition.

3722

"labels": [ # The set of labels that can be used to describe a specific

3723

# instance of this metric type. For example, the

3724

# `appengine.googleapis.com/http/server/response_latencies` metric

3725

# type has a label for the HTTP response code, `response_code`, so

3726

# you can look at latencies for successful responses or just

3727

# for responses that failed.

3728

{ # A description of a label.

3729

"key": "A String", # The label key.

3730

"description": "A String", # A human-readable description for the label.

3731

"valueType": "A String", # The type of data that can be assigned to the label.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3732

},

3733

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3734

},

3735

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3736

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3737

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3738

# Example for an API targeted for external use:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3739

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3740

# name: calendar.googleapis.com

3741

# authentication:

3742

# providers:

3743

# - id: google_calendar_auth

3744

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3745

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3746

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3747

# - selector: "*"

3748

# requirements:

3749

# provider_id: google_calendar_auth

3750

"rules": [ # A list of authentication rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3751

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3752

# **NOTE:** All service configuration rules follow "last one wins" order.

3753

{ # Authentication rules for the service.

3754

#

3755

# By default, if a method has any authentication requirements, every request

3756

# must include a valid credential matching one of the requirements.

3757

# It's an error to include more than one kind of credential in a single

3758

# request.

3759

#

3760

# If a method doesn't have any auth requirements, request credentials will be

3761

# ignored.

3762

"requirements": [ # Requirements for additional authentication providers.

3763

{ # User-defined authentication requirements, including support for

3764

# [JSON Web Token

3765

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3766

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3771

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3772

# implemented and accepted in all the runtime components.

3773

#

3774

# The list of JWT

3775

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3776

# that are allowed to access. A JWT containing any of these audiences will

3777

# be accepted. When this setting is absent, only JWTs with audience

3778

# "https://Service_name/API_name"

3779

# will be accepted. For example, if no audiences are in the setting,

3780

# LibraryService API will only accept JWTs with the following audience

3781

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3786

# bookstore_web.apps.googleusercontent.com

3787

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3788

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3789

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3790

#

3791

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3792

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

3793

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3794

# there are scopes defined for "Read-only access to Google Calendar" and

3795

# "Access to Cloud Platform". Users can consent to a scope for an application,

3796

# giving it permission to access that data on their behalf.

3797

#

3798

# OAuth scope specifications should be fairly coarse grained; a user will need

3799

# to see and understand the text description of what your scope means.

3800

#

3801

# In most cases: use one or at most two OAuth scopes for an entire family of

3802

# products. If your product has multiple APIs, you should probably be sharing

3803

# the OAuth scope across all of those APIs.

3804

#

3805

# When you need finer grained OAuth consent screens: talk with your product

3806

# management about how developers will use them in practice.

3807

#

3808

# Please note that even though each of the canonical scopes is enough for a

3809

# request to be accepted and passed to the backend, a request can still fail

3810

# due to the backend requiring additional scopes or permissions.

3811

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3812

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3817

# https://www.googleapis.com/auth/calendar.read

},

},

],

"providers": [ # Defines a set of authentication providers that a service supports.

3822

{ # Configuration for an authentication provider, including support for

3823

# [JSON Web Token

3824

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3825

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3826

# [OpenID

3827

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3828

# Optional if the key set document:

3829

# - can be retrieved from

3830

# [OpenID

3831

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

3832

# the issuer.

3833

# - can be inferred from the email domain of the issuer (e.g. a Google

3834

# service account).

3835

#

3836

# Example: https://www.googleapis.com/oauth2/v1/certs

3837

"audiences": "A String", # The list of JWT

3838

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3839

# that are allowed to access. A JWT containing any of these audiences will

3840

# be accepted. When this setting is absent, JWTs with audiences:

3841

# - "https://[service.name]/[google.protobuf.Api.name]"

3842

# - "https://[service.name]/"

3843

# will be accepted.

3844

# For example, if no audiences are in the setting, LibraryService API will

3845

# accept JWTs with the following audiences:

3846

# -

3847

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

3848

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3853

# bookstore_web.apps.googleusercontent.com

3854

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

3855

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

3856

"issuer": "A String", # Identifies the principal that issued the JWT. See

3857

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3858

# Usually a URL or an email address.

3859

#

3860

# Example: https://securetoken.google.com

3861

# Example: 1234567-compute@developer.gserviceaccount.com

3862

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3863

# `AuthRequirement.provider_id`.

3864

#

3865

# Example: "bookstore_auth".

3866

"jwtLocations": [ # Defines the locations to extract the JWT.

3867

#

3868

# JWT locations can be either from HTTP headers or URL query parameters.

3869

# The rule is that the first match wins. The checking order is: checking

3870

# all headers first, then URL query parameters.

3871

#

3872

# If not specified, default to use following 3 locations:

3873

# 1) Authorization: Bearer

3874

# 2) x-goog-iap-jwt-assertion

3875

# 3) access_token query parameter

3876

#

3877

# Default locations can be specified as followings:

3878

# jwt_locations:

3879

# - header: Authorization

3880

# value_prefix: "Bearer "

3881

# - header: x-goog-iap-jwt-assertion

3882

# - query: access_token

3883

{ # Specifies a location to extract JWT from an API request.

3884

"header": "A String", # Specifies HTTP header name to extract JWT token.

3885

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

3886

# Only applies to "in" header type. Must be empty for "in" query type.

3887

# If not empty, the header value has to match (case sensitive) this prefix.

3888

# If not matched, JWT will not be extracted. If matched, JWT will be

3889

# extracted after the prefix is removed.

3890

#

3891

# For example, for "Authorization: Bearer {JWT}",

3892

# value_prefix="Bearer " with a space at the end.

3893

"query": "A String", # Specifies URL query parameter name to extract JWT token.

3894

},

3895

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3896

},

3897

],

3898

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3899

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3900

# service controller handles features like abuse, quota, billing, logging,

3901

# monitoring, etc.

3902

"environment": "A String", # The service control environment to use. If empty, no control plane

3903

# feature (like quota and billing) will be enabled.

3904

},

3905

"configVersion": 42, # The semantic version of the service configuration. The config version

3906

# affects the interpretation of the service configuration. For example,

3907

# certain features are enabled by default for certain config versions.

3908

#

3909

# The latest config version is `3`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3914

<code class="details" id="get">get(serviceName, configId, view=None, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3915

<pre>Gets a service configuration (version) for a managed service.

3916

3917

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3918

serviceName: string, Required. The name of the service. See the [overview](/service-management/overview)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3919

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3920

configId: string, Required. The id of the service configuration resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3921

3922

This field must be specified for the server to return all fields, including

3923

`SourceInfo`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3924

view: string, Specifies which parts of the Service Config should be returned in the

3925

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3926

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3933

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3934

{ # `Service` is the root object of Google service configuration schema. It

3935

# describes basic information about a service, such as the name and the

3936

# title, and delegates other aspects to sub-sections. Each sub-section is

3937

# either a proto message or a repeated proto message that configures a

3938

# specific aspect, such as auth. See each proto message definition for details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

#

# Example:

#

# type: google.api.Service

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3943

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3944

# name: calendar.googleapis.com

3945

# title: Google Calendar API

3946

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3947

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3948

# authentication:

3949

# providers:

3950

# - id: google_calendar_auth

3951

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3952

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3953

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3954

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3955

# requirements:

3956

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3957

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3958

#

3959

# The example below shows how to configure monitored resources and metrics

3960

# for monitoring. In the example, a monitored resource and two metrics are

3961

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3962

# to both producer and consumer projects, whereas the

3963

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3964

# consumer project.

3965

#

3966

# monitored_resources:

3967

# - type: library.googleapis.com/branch

3968

# labels:

3969

# - key: /city

3970

# description: The city where the library branch is located in.

3971

# - key: /name

3972

# description: The name of the branch.

3973

# metrics:

3974

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3979

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3984

# monitoring:

3985

# producer_destinations:

3986

# - monitored_resource: library.googleapis.com/branch

3987

# metrics:

3988

# - library.googleapis.com/book/returned_count

3989

# consumer_destinations:

3990

# - monitored_resource: library.googleapis.com/branch

3991

# metrics:

3992

# - library.googleapis.com/book/returned_count

3993

# - library.googleapis.com/book/overdue_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3994

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3995

# There can be multiple consumer destinations. A monitored resouce type may

3996

# appear in multiple monitoring destinations if different aggregations are

3997

# needed for different sets of metrics associated with that monitored

3998

# resource type. A monitored resource and metric pair may only be used once

3999

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4000

{ # Configuration of a specific monitoring destination (the producer project

4001

# or the consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4002

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4003

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4004

"metrics": [ # Types of the metrics to report to this monitoring destination.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4005

# Each type must be defined in Service.metrics section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

"A String",

],

},

],

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4011

# There can be multiple producer destinations. A monitored resouce type may

4012

# appear in multiple monitoring destinations if different aggregations are

4013

# needed for different sets of metrics associated with that monitored

4014

# resource type. A monitored resource and metric pair may only be used once

4015

# in the Monitoring configuration.

4016

{ # Configuration of a specific monitoring destination (the producer project

4017

# or the consumer project).

4018

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4019

# Service.monitored_resources section.

4020

"metrics": [ # Types of the metrics to report to this monitoring destination.

4021

# Each type must be defined in Service.metrics section.

4022

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

],

},

],

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4027

"systemTypes": [ # A list of all proto message types included in this API service.

4028

# It serves similar purpose as [google.api.Service.types], except that

4029

# these types are not needed by user-defined APIs. Therefore, they will not

4030

# show up in the generated discovery doc. This field should only be used

4031

# to define system APIs in ESF.

4032

{ # A protocol buffer message type.

4033

"options": [ # The protocol buffer options.

4034

{ # A protocol buffer option, which can be attached to a message, field,

4035

# enumeration, etc.

4036

"value": { # The option's value packed in an Any message. If the value is a primitive,

4037

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4038

# should be used. If the value is an enum, it should be stored as an int32

4039

# value using the google.protobuf.Int32Value type.

4040

"a_key": "", # Properties of the object. Contains field @type with type URL.

4041

},

4042

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4043

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4044

# For custom options, it should be the fully-qualified name. For example,

4045

# `"google.api.http"`.

4046

},

4047

],

4048

"fields": [ # The list of fields.

4049

{ # A single field of a message type.

4050

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4051

"name": "A String", # The field name.

4052

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4053

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4054

"number": 42, # The field number.

4055

"kind": "A String", # The field type.

4056

"jsonName": "A String", # The field JSON name.

4057

"options": [ # The protocol buffer options.

4058

{ # A protocol buffer option, which can be attached to a message, field,

4059

# enumeration, etc.

4060

"value": { # The option's value packed in an Any message. If the value is a primitive,

4061

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4062

# should be used. If the value is an enum, it should be stored as an int32

4063

# value using the google.protobuf.Int32Value type.

4064

"a_key": "", # Properties of the object. Contains field @type with type URL.

4065

},

4066

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4067

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4068

# For custom options, it should be the fully-qualified name. For example,

4069

# `"google.api.http"`.

4070

},

4071

],

4072

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4073

# types. The first type has index 1; zero means the type is not in the list.

4074

"packed": True or False, # Whether to use alternative packed wire representation.

4075

"cardinality": "A String", # The field cardinality.

4076

},

4077

],

4078

"name": "A String", # The fully qualified message name.

4079

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4080

"A String",

4081

],

4082

"syntax": "A String", # The source syntax.

4083

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4084

# protobuf element, like the file in which it is defined.

4085

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4086

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"producerProjectId": "A String", # The Google project that owns this service.

4091

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

4092

# usage.

4093

#

4094

# The metric based quota configuration works this way:

4095

# - The service configuration defines a set of metrics.

4096

# - For API calls, the quota.metric_rules maps methods to metrics with

4097

# corresponding costs.

4098

# - The quota.limits defines limits on the metrics, which will be used for

4099

# quota checks at runtime.

4100

#

4101

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

4107

# metric: library.googleapis.com/write_calls

4108

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

4114

# # except for the UpdateBook and DeleteBook methods. These two methods

4115

# # are mapped to the write_calls metric, with the UpdateBook method

4116

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

4121

# - selector: google.example.library.v1.LibraryService.UpdateBook

4122

# metric_costs:

4123

# library.googleapis.com/write_calls: 2

4124

# - selector: google.example.library.v1.LibraryService.DeleteBook

4125

# metric_costs:

4126

# library.googleapis.com/write_calls: 1

4127

#

4128

# Corresponding Metric definition:

4129

#

4130

# metrics:

4131

# - name: library.googleapis.com/read_calls

4132

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

4137

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

4142

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

4143

# for a limit type. There can be at most one limit for a duration and limit

4144

# type combination defined within a `QuotaGroup`.

4145

"name": "A String", # Name of the quota limit.

4146

#

4147

# The name must be provided, and it must be unique within the service. The

4148

# name can only include alphanumeric characters as well as '-'.

4149

#

4150

# The maximum length of the limit name is 64 characters.

4151

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

4152

# The free tier is the number of tokens that will be subtracted from the

4153

# billed amount when billing is enabled.

4154

# This field can only be set on a limit with duration "1d", in a billable

4155

# group; it is invalid on any other limit. If this field is not set, it

4156

# defaults to 0, indicating that there is no free tier for this service.

4157

#

4158

# Used by group-based quotas only.

4159

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

4160

#

4161

# Used by group-based quotas only.

4162

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

4163

# duration. This is the number of tokens assigned when a client

4164

# application developer activates the service for his/her project.

4165

#

4166

# Specifying a value of 0 will block all requests. This can be used if you

4167

# are provisioning quota to selected consumers and blocking others.

4168

# Similarly, a value of -1 will indicate an unlimited quota. No other

4169

# negative values are allowed.

4170

#

4171

# Used by group-based quotas only.

4172

"description": "A String", # Optional. User-visible, extended description for this quota limit.

4173

# Should be used only when more context is needed to understand this limit

4174

# than provided by the limit's display name (see: `display_name`).

4175

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

4176

# the same metric will be checked together during runtime. The metric must be

4177

# defined within the service config.

4178

"displayName": "A String", # User-visible display name for this limit.

4179

# Optional. If not set, the UI will provide a default display name based on

4180

# the quota configuration. This field can be used to override the default

4181

# display name generated from the configuration.

4182

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

4183

# integer value that is the maximum number of requests allowed for the

4184

# specified unit. Currently only STANDARD is supported.

4185

"a_key": "A String",

4186

},

4187

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

4188

# Metric.unit. The supported unit kinds are determined by the quota

4189

# backend system.

4190

#

4191

# Here are some examples:

4192

# * "1/min/{project}" for quota per minute per project.

4193

#

4194

# Note: the order of unit components is insignificant.

4195

# The "1" at the beginning is required to follow the metric unit syntax.

4196

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

4197

# duration. Client application developers can override the default limit up

4198

# to this maximum. If specified, this value cannot be set to a value less

4199

# than the default limit. If not specified, it is set to the default limit.

4200

#

4201

# To allow clients to apply overrides with no upper bound, set this to -1,

4202

# indicating unlimited maximum quota.

4203

#

4204

# Used by group-based quotas only.

4205

},

4206

],

4207

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

4208

# or more metrics.

4209

{ # Bind API methods to metrics. Binding a method to a metric causes that

4210

# metric's configured quota behaviors to apply to the method call.

4211

"selector": "A String", # Selects the methods to which this rule applies.

4212

#

4213

# Refer to selector for syntax details.

4214

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

4215

# cost applied to each metric.

4216

#

4217

# The key of the map is the metric name, and the values are the amount

4218

# increased for the metric against which the quota limits are defined.

4219

# The value must not be negative.

"a_key": "A String",

},

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

4226

# service, such as `calendar.googleapis.com`. The service name

4227

# typically goes through DNS verification to make sure the owner

4228

# of the service also owns the DNS name.

4229

"billing": { # Billing related configuration of the service. # Billing configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4230

#

4231

# The following example shows how to configure monitored resources and metrics

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4232

# for billing, `consumer_destinations` is the only supported destination and

4233

# the monitored resources need at least one label key

4234

# `cloud.googleapis.com/location` to indicate the location of the billing

4235

# usage, using different monitored resources between monitoring and billing is

4236

# recommended so they can be evolved independently:

4237

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4238

#

4239

# monitored_resources:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4240

# - type: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4241

# labels:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4242

# - key: cloud.googleapis.com/location

4243

# description: |

4244

# Predefined label to support billing location restriction.

4245

# - key: city

4246

# description: |

4247

# Custom label to define the city where the library branch is located

4248

# in.

4249

# - key: name

4250

# description: Custom label to define the name of the library branch.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4251

# metrics:

4252

# - name: library.googleapis.com/book/borrowed_count

4253

# metric_kind: DELTA

4254

# value_type: INT64

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4255

# unit: "1"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4256

# billing:

4257

# consumer_destinations:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4258

# - monitored_resource: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4259

# metrics:

4260

# - library.googleapis.com/book/borrowed_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4261

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4262

# There can be multiple consumer destinations per service, each one must have

4263

# a different monitored resource type. A metric can be used in at most

4264

# one consumer destination.

4265

{ # Configuration of a specific billing destination (Currently only support

4266

# bill against consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4267

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4268

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4269

"metrics": [ # Names of the metrics to report to this billing destination.

4270

# Each name must be defined in Service.metrics section.

4271

"A String",

4272

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4273

},

4274

],

4275

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4276

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4277

# specific protobuf types that can appear in error detail lists of

4278

# error responses.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4279

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4280

# Example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4281

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4282

# custom_error:

4283

# types:

4284

# - google.foo.v1.CustomError

4285

# - google.foo.v1.AnotherError

4286

"rules": [ # The list of custom error rules that apply to individual API messages.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4287

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4288

# **NOTE:** All service configuration rules follow "last one wins" order.

4289

{ # A custom error rule.

4290

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4291

# objects of this type will be filtered when they appear in error payload.

4292

"selector": "A String", # Selects messages to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4293

#

4294

# Refer to selector for syntax details.

4295

},

4296

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4297

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

4298

"A String",

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4299

],

4300

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4301

"title": "A String", # The product title for this service.

4302

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4303

# with the same name as the service is automatically generated to service all

4304

# defined APIs.

4305

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4306

# A service may expose any number of endpoints, and all endpoints share the

4307

# same service configuration, such as quota configuration and monitoring

4308

# configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4309

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4310

# Example service configuration:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4311

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4312

# name: library-example.googleapis.com

4313

# endpoints:

4314

# # Below entry makes 'google.example.library.v1.Library'

4315

# # API be served from endpoint address library-example.googleapis.com.

4316

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4317

# # it to decide whether the subsequent cross-origin request is

4318

# # allowed to proceed.

4319

# - name: library-example.googleapis.com

4320

# allow_cors: true

4321

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4322

# please specify multiple google.api.Endpoint for each of the intended

4323

# aliases.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4324

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4325

# Additional names that this endpoint will be hosted on.

4326

"A String",

4327

],

4328

"features": [ # The list of features enabled on this endpoint.

4329

"A String",

4330

],

4331

"allowCors": True or False, # Allowing

4332

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4333

# cross-domain traffic, would allow the backends served from this endpoint to

4334

# receive and respond to HTTP OPTIONS requests. The response will be used by

4335

# the browser to determine whether the subsequent cross-origin request is

4336

# allowed to proceed.

4337

"name": "A String", # The canonical name of this endpoint.

4338

"target": "A String", # The specification of an Internet routable address of API frontend that will

4339

# handle requests to this [API

4340

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

4341

# either a valid IPv4 address or a fully-qualified domain name. For example,

4342

# "8.8.8.8" or "myservice.appspot.com".

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4343

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4344

],

4345

"logs": [ # Defines the logs used by this service.

4346

{ # A description of a log type. Example in YAML format:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4347

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4348

# - name: library.googleapis.com/activity_history

4349

# description: The history of borrowing and returning library items.

4350

# display_name: Activity

4351

# labels:

4352

# - key: /customer_id

4353

# description: Identifier of a library customer

4354

"labels": [ # The set of labels that are available to describe a specific log entry.

4355

# Runtime requests that contain labels not specified here are

4356

# considered invalid.

4357

{ # A description of a label.

4358

"key": "A String", # The label key.

4359

"description": "A String", # A human-readable description for the label.

4360

"valueType": "A String", # The type of data that can be assigned to the label.

4361

},

4362

],

4363

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4364

# include the following characters: upper- and lower-case alphanumeric

4365

# characters [A-Za-z0-9], and punctuation characters including

4366

# slash, underscore, hyphen, period [/_-.].

4367

"description": "A String", # A human-readable description of this log. This information appears in

4368

# the documentation and can contain details.

4369

"displayName": "A String", # The human-readable name for this log. This information appears on

4370

# the user interface and should be concise.

4371

},

4372

],

4373

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4374

# of the google.protobuf.Api needs to be provided by the configuration

4375

# author, as the remaining fields will be derived from the IDL during the

4376

# normalization process. It is an error to specify an API interface here

4377

# which cannot be resolved against the associated IDL files.

4378

{ # Api is a light-weight descriptor for an API Interface.

4379

#

4380

# Interfaces are also described as "protocol buffer services" in some contexts,

4381

# such as by the "service" keyword in a .proto file, but they are different

4382

# from API Services, which represent a concrete implementation of an interface

4383

# as opposed to simply a description of methods and bindings. They are also

4384

# sometimes simply referred to as "APIs" in other contexts, such as the name of

4385

# this message itself. See https://cloud.google.com/apis/design/glossary for

4386

# detailed terminology.

4387

"options": [ # Any metadata attached to the interface.

4388

{ # A protocol buffer option, which can be attached to a message, field,

4389

# enumeration, etc.

4390

"value": { # The option's value packed in an Any message. If the value is a primitive,

4391

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4392

# should be used. If the value is an enum, it should be stored as an int32

4393

# value using the google.protobuf.Int32Value type.

4394

"a_key": "", # Properties of the object. Contains field @type with type URL.

4395

},

4396

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4397

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4398

# For custom options, it should be the fully-qualified name. For example,

4399

# `"google.api.http"`.

4400

},

4401

],

4402

"methods": [ # The methods of this interface, in unspecified order.

4403

{ # Method represents a method of an API interface.

4404

"responseTypeUrl": "A String", # The URL of the output message type.

4405

"options": [ # Any metadata attached to the method.

4406

{ # A protocol buffer option, which can be attached to a message, field,

4407

# enumeration, etc.

4408

"value": { # The option's value packed in an Any message. If the value is a primitive,

4409

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4410

# should be used. If the value is an enum, it should be stored as an int32

4411

# value using the google.protobuf.Int32Value type.

4412

"a_key": "", # Properties of the object. Contains field @type with type URL.

4413

},

4414

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4415

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4416

# For custom options, it should be the fully-qualified name. For example,

4417

# `"google.api.http"`.

4418

},

4419

],

4420

"responseStreaming": True or False, # If true, the response is streamed.

4421

"name": "A String", # The simple name of this method.

4422

"requestTypeUrl": "A String", # A URL of the input message type.

4423

"requestStreaming": True or False, # If true, the request is streamed.

4424

"syntax": "A String", # The source syntax of this method.

4425

},

4426

],

4427

"name": "A String", # The fully qualified name of this interface, including package name

4428

# followed by the interface's simple name.

4429

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4430

# message.

4431

# protobuf element, like the file in which it is defined.

4432

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4433

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4434

},

4435

"syntax": "A String", # The source syntax of the service.

4436

"version": "A String", # A version string for this interface. If specified, must have the form

4437

# `major-version.minor-version`, as in `1.10`. If the minor version is

4438

# omitted, it defaults to zero. If the entire version field is empty, the

4439

# major version is derived from the package name, as outlined below. If the

4440

# field is not empty, the version in the package name will be verified to be

4441

# consistent with what is provided here.

4442

#

4443

# The versioning schema uses [semantic

4444

# versioning](http://semver.org) where the major version number

4445

# indicates a breaking change and the minor version an additive,

4446

# non-breaking change. Both version numbers are signals to users

4447

# what to expect from different versions, and should be carefully

4448

# chosen based on the product plan.

4449

#

4450

# The major version is also reflected in the package name of the

4451

# interface, which must end in `v<major-version>`, as in

4452

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4453

# be omitted. Zero major versions must only be used for

4454

# experimental, non-GA interfaces.

4455

"mixins": [ # Included interfaces. See Mixin.

4456

{ # Declares an API Interface to be included in this interface. The including

4457

# interface must redeclare all the methods from the included interface, but

4458

# documentation and options are inherited as follows:

4459

#

4460

# - If after comment and whitespace stripping, the documentation

4461

# string of the redeclared method is empty, it will be inherited

4462

# from the original method.

4463

#

4464

# - Each annotation belonging to the service config (http,

4465

# visibility) which is not set in the redeclared method will be

4466

# inherited.

4467

#

4468

# - If an http annotation is inherited, the path pattern will be

4469

# modified as follows. Any version prefix will be replaced by the

4470

# version of the including interface plus the root path if

4471

# specified.

4472

#

4473

# Example of a simple mixin:

4474

#

4475

# package google.acl.v1;

4476

# service AccessControl {

4477

# // Get the underlying ACL object.

4478

# rpc GetAcl(GetAclRequest) returns (Acl) {

4479

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4484

# service Storage {

4485

# // rpc GetAcl(GetAclRequest) returns (Acl);

4486

#

4487

# // Get a data record.

4488

# rpc GetData(GetDataRequest) returns (Data) {

4489

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4494

#

4495

# apis:

4496

# - name: google.storage.v2.Storage

4497

# mixins:

4498

# - name: google.acl.v1.AccessControl

4499

#

4500

# The mixin construct implies that all methods in `AccessControl` are

4501

# also declared with same name and request/response types in

4502

# `Storage`. A documentation generator or annotation processor will

4503

# see the effective `Storage.GetAcl` method after inherting

4504

# documentation and annotations as follows:

4505

#

4506

# service Storage {

4507

# // Get the underlying ACL object.

4508

# rpc GetAcl(GetAclRequest) returns (Acl) {

4509

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4515

#

4516

# If the `root` field in the mixin is specified, it should be a

4517

# relative path under which inherited HTTP paths are placed. Example:

4518

#

4519

# apis:

4520

# - name: google.storage.v2.Storage

4521

# mixins:

4522

# - name: google.acl.v1.AccessControl

4523

# root: acls

4524

#

4525

# This implies the following inherited HTTP annotation:

4526

#

4527

# service Storage {

4528

# // Get the underlying ACL object.

4529

# rpc GetAcl(GetAclRequest) returns (Acl) {

4530

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"name": "A String", # The fully qualified name of the interface which is included.

4535

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

# are rooted.

},

],

},

],

"types": [ # A list of all proto message types included in this API service.

4542

# Types referenced directly or indirectly by the `apis` are

4543

# automatically included. Messages which are not referenced but

4544

# shall be included, such as types used by the `google.protobuf.Any` type,

4545

# should be listed here by name. Example:

4546

#

4547

# types:

4548

# - name: google.protobuf.Int32

4549

{ # A protocol buffer message type.

4550

"options": [ # The protocol buffer options.

4551

{ # A protocol buffer option, which can be attached to a message, field,

4552

# enumeration, etc.

4553

"value": { # The option's value packed in an Any message. If the value is a primitive,

4554

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4555

# should be used. If the value is an enum, it should be stored as an int32

4556

# value using the google.protobuf.Int32Value type.

4557

"a_key": "", # Properties of the object. Contains field @type with type URL.

4558

},

4559

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4560

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4561

# For custom options, it should be the fully-qualified name. For example,

4562

# `"google.api.http"`.

4563

},

4564

],

4565

"fields": [ # The list of fields.

4566

{ # A single field of a message type.

4567

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4568

"name": "A String", # The field name.

4569

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4570

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4571

"number": 42, # The field number.

4572

"kind": "A String", # The field type.

4573

"jsonName": "A String", # The field JSON name.

4574

"options": [ # The protocol buffer options.

4575

{ # A protocol buffer option, which can be attached to a message, field,

4576

# enumeration, etc.

4577

"value": { # The option's value packed in an Any message. If the value is a primitive,

4578

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4579

# should be used. If the value is an enum, it should be stored as an int32

4580

# value using the google.protobuf.Int32Value type.

4581

"a_key": "", # Properties of the object. Contains field @type with type URL.

4582

},

4583

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4584

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4585

# For custom options, it should be the fully-qualified name. For example,

4586

# `"google.api.http"`.

4587

},

4588

],

4589

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4590

# types. The first type has index 1; zero means the type is not in the list.

4591

"packed": True or False, # Whether to use alternative packed wire representation.

4592

"cardinality": "A String", # The field cardinality.

4593

},

4594

],

4595

"name": "A String", # The fully qualified message name.

4596

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4597

"A String",

4598

],

4599

"syntax": "A String", # The source syntax.

4600

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4601

# protobuf element, like the file in which it is defined.

4602

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4603

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

4608

"sourceFiles": [ # All files used during config generation.

4609

{

4610

"a_key": "", # Properties of the object. Contains field @type with type URL.

4611

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4612

],

4613

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4614

"http": { # Defines the HTTP configuration for an API service. It contains a list of # HTTP configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4615

# HttpRule, each specifying the mapping of an RPC method

4616

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4617

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

4618

# cases of single segment matches in reserved expansion, where "%2F" will be

4619

# left encoded.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4620

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4621

# The default behavior is to not decode RFC 6570 reserved characters in multi

4622

# segment matches.

4623

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4624

#

4625

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4626

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4627

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4628

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

4629

# more HTTP REST endpoints. It allows developers to build a single API service

4630

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

4631

# APIs](https://github.com/googleapis/googleapis),

4632

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

4633

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

4634

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

4635

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4636

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4637

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

4638

# how different portions of the gRPC request message are mapped to the URL

4639

# path, URL query parameters, and HTTP request body. It also controls how the

4640

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

4641

# typically specified as an `google.api.http` annotation on the gRPC method.

4642

#

4643

# Each mapping specifies a URL path template and an HTTP method. The path

4644

# template may refer to one or more fields in the gRPC request message, as long

4645

# as each field is a non-repeated field with a primitive (non-message) type.

4646

# The path template controls how fields of the request message are mapped to

4647

# the URL path.

4648

#

4649

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4650

#

4651

# service Messaging {

4652

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4653

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4654

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4655

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4656

# }

4657

# }

4658

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4659

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4660

# }

4661

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4662

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4663

# }

4664

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4665

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4666

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4667

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4668

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4669

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4670

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4671

# Any fields in the request message which are not bound by the path template

4672

# automatically become HTTP query parameters if there is no HTTP request body.

4673

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4674

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4675

# service Messaging {

4676

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4677

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4678

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4679

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4680

# }

4681

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4682

# message GetMessageRequest {

4683

# message SubMessage {

4684

# string subfield = 1;

4685

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4686

# string message_id = 1; // Mapped to URL path.

4687

# int64 revision = 2; // Mapped to URL query parameter `revision`.

4688

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4689

# }

4690

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4691

# This enables a HTTP JSON to RPC mapping as below:

4692

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4693

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4694

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4695

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4696

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

4697

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4698

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4699

# Note that fields which are mapped to URL query parameters must have a

4700

# primitive type or a repeated primitive type or a non-repeated message type.

4701

# In the case of a repeated type, the parameter can be repeated in the URL

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4702

# as `...?param=A&param=B`. In the case of a message type, each field of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4703

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4704

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4705

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4706

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4707

# specifies the mapping. Consider a REST update method on the

4708

# message resource collection:

4709

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4710

# service Messaging {

4711

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4712

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4713

# patch: "/v1/messages/{message_id}"

4714

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

4719

# string message_id = 1; // mapped to the URL

4720

# Message message = 2; // mapped to the body

4721

# }

4722

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4723

# The following HTTP JSON to RPC mapping is enabled, where the

4724

# representation of the JSON in the request body is determined by

4725

# protos JSON encoding:

4726

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4727

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4728

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4729

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4730

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4731

#

4732

# The special name `*` can be used in the body mapping to define that

4733

# every field not bound by the path template should be mapped to the

4734

# request body. This enables the following alternative definition of

4735

# the update method:

4736

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4737

# service Messaging {

4738

# rpc UpdateMessage(Message) returns (Message) {

4739

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4740

# patch: "/v1/messages/{message_id}"

4741

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

4747

# string text = 2;

4748

# }

4749

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4750

#

4751

# The following HTTP JSON to RPC mapping is enabled:

4752

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4753

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4754

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4755

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4756

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4757

#

4758

# Note that when using `*` in the body mapping, it is not possible to

4759

# have HTTP parameters, as all fields not bound by the path end in

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4760

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4761

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4762

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4763

#

4764

# It is possible to define multiple HTTP methods for one RPC by using

4765

# the `additional_bindings` option. Example:

4766

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4767

# service Messaging {

4768

# rpc GetMessage(GetMessageRequest) returns (Message) {

4769

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4770

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4771

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4772

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4773

# }

4774

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4775

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4776

# }

4777

# message GetMessageRequest {

4778

# string message_id = 1;

4779

# string user_id = 2;

4780

# }

4781

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4782

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4783

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4784

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4785

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4786

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4787

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

4788

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4789

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4790

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4791

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4792

# 1. Leaf request fields (recursive expansion nested messages in the request

4793

# message) are classified into three categories:

4794

# - Fields referred by the path template. They are passed via the URL path.

4795

# - Fields referred by the HttpRule.body. They are passed via the HTTP

4796

# request body.

4797

# - All other fields are passed via the URL query parameters, and the

4798

# parameter name is the field path in the request message. A repeated

4799

# field can be represented as multiple query parameters under the same

4800

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4801

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4802

# are passed via URL path and HTTP request body.

4803

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

4804

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4805

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4806

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4807

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4808

# Template = "/" Segments [ Verb ] ;

4809

# Segments = Segment { "/" Segment } ;

4810

# Segment = "*" | "**" | LITERAL | Variable ;

4811

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4812

# FieldPath = IDENT { "." IDENT } ;

4813

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4814

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4815

# The syntax `*` matches a single URL path segment. The syntax `**` matches

4816

# zero or more URL path segments, which must be the last part of the URL path

4817

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4818

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4819

# The syntax `Variable` matches part of the URL path as specified by its

4820

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4821

# matches a single path segment, its template may be omitted, e.g. `{var}`

4822

# is equivalent to `{var=*}`.

4823

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4824

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

4825

# contains any reserved character, such characters should be percent-encoded

4826

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4827

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4828

# If a variable contains exactly one path segment, such as `"{var}"` or

4829

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4830

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

4831

# server side does the reverse decoding. Such variables show up in the

4832

# [Discovery

4833

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4834

# `{var}`.

4835

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4836

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

4837

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4838

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4839

# The server side does the reverse decoding, except "%2F" and "%2f" are left

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4840

# unchanged. Such variables show up in the

4841

# [Discovery

4842

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4843

# `{+var}`.

4844

#

4845

# ## Using gRPC API Service Configuration

4846

#

4847

# gRPC API Service Configuration (service config) is a configuration language

4848

# for configuring a gRPC service to become a user-facing product. The

4849

# service config is simply the YAML representation of the `google.api.Service`

4850

# proto message.

4851

#

4852

# As an alternative to annotating your proto file, you can configure gRPC

4853

# transcoding in your service config YAML files. You do this by specifying a

4854

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

4855

# effect as the proto annotation. This can be particularly useful if you

4856

# have a proto that is reused in multiple services. Note that any transcoding

4857

# specified in the service config will override any matching transcoding

4858

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

4865

# - selector: example.v1.Messaging.GetMessage

4866

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

4871

# proto to JSON conversion must follow the [proto3

4872

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

4873

#

4874

# While the single segment variable follows the semantics of

4875

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4876

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

4877

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

4878

# does not expand special characters like `?` and `#`, which would lead

4879

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

4880

# for multi segment variables.

4881

#

4882

# The path variables **must not** refer to any repeated or mapped field,

4883

# because client libraries are not capable of handling such variable expansion.

4884

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4885

# The path variables **must not** capture the leading "/" character. The reason

4886

# is that the most common use case "{var}" does not capture the leading "/"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4887

# character. For consistency, all path variables must share the same behavior.

4888

#

4889

# Repeated message fields must not be mapped to URL query parameters, because

4890

# no client library can support such complicated mapping.

4891

#

4892

# If an API needs to use a JSON array for request or response body, it can map

4893

# the request or response body to a repeated field. However, some gRPC

4894

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4895

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

4896

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4897

# not contain an `additional_bindings` field themselves (that is,

4898

# the nesting may only be one level deep).

4899

# Object with schema name: HttpRule

4900

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4901

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4902

# response body. When omitted, the entire response message will be used

4903

# as the HTTP response body.

4904

#

4905

# NOTE: The referred field must be present at the top-level of the response

4906

# message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4907

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

4908

# body, or `*` for mapping all request fields not captured by the path

4909

# pattern to the HTTP body, or omitted for not having any HTTP request body.

4910

#

4911

# NOTE: the referred field must be present at the top-level of the request

4912

# message type.

4913

"selector": "A String", # Selects a method to which this rule applies.

4914

#

4915

# Refer to selector for syntax details.

4916

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

4917

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

4918

# included in the `pattern` field, such as HEAD, or "*" to leave the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4919

# HTTP method unspecified for this rule. The wild-card rule is useful

4920

# for services that provide content to Web (HTML) clients.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4921

"kind": "A String", # The name of this custom HTTP verb.

4922

"path": "A String", # The path matched by this custom verb.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4923

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4924

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

4925

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

4926

# resources.

4927

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

4928

# half-duplex streaming method.

4929

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4930

},

4931

],

4932

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4933

"systemParameters": { # ### System parameter configuration # System parameter configuration.

4934

#

4935

# A system parameter is a special kind of parameter defined by the API

4936

# system, not by an individual API. It is typically mapped to an HTTP header

4937

# and/or a URL query parameter. This configuration specifies which methods

4938

# change the names of the system parameters.

4939

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4940

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4941

# The parameters defined here will override the default parameters

4942

# implemented by the system. If this field is missing from the service

4943

# config, default system parameters will be used. Default system parameters

4944

# and names is implementation-dependent.

4945

#

4946

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4954

#

4955

#

4956

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4961

# parameters:

4962

# - name: api_key

4963

# http_header: Api-Key1

4964

# - name: api_key

4965

# http_header: Api-Key2

4966

#

4967

# **NOTE:** All service configuration rules follow "last one wins" order.

4968

{ # Define a system parameter rule mapping system parameter definitions to

4969

# methods.

4970

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4971

# For a given method call, only one of them should be used. If multiple

4972

# names are used the behavior is implementation-dependent.

4973

# If none of the specified names are present the behavior is

4974

# parameter-dependent.

4975

{ # Define a parameter's name and location. The parameter may be passed as either

4976

# an HTTP header or a URL query parameter, and if both are passed the behavior

4977

# is implementation-dependent.

4978

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

4979

# insensitive.

4980

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

4981

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4982

# sensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4983

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4984

],

4985

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4986

# methods in all APIs.

4987

#

4988

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4993

"rules": [ # A list of API backend rules that apply to individual API methods.

4994

#

4995

# **NOTE:** All service configuration rules follow "last one wins" order.

4996

{ # A backend rule provides configuration for an individual API element.

4997

"protocol": "A String", # The protocol used for sending a request to the backend.

4998

# The supported values are "http/1.1" and "h2".

4999

#

5000

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

5010

# to "h2" for improved performance.

5011

#

5012

# Configuring this field to non-default values is only supported for secure

5013

# HTTP backends. This field will be ignored for all other backends.

5014

#

5015

# See

5016

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

5017

# for more details on the supported values.

5018

"selector": "A String", # Selects the methods to which this rule applies.

5019

#

5020

# Refer to selector for syntax details.

5021

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

5022

# operation. The default is no deadline.

5023

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

5024

# varies based on the request protocol and deployment environment.

5025

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

5026

# value lower than this will be rejected.

5027

"address": "A String", # The address of the API backend.

5028

#

5029

# The scheme is used to determine the backend protocol and security.

5030

# The following schemes are accepted:

5031

#

5032

# SCHEME PROTOCOL SECURITY

# http:// HTTP None

# https:// HTTP TLS

# grpc:// gRPC None

# grpcs:// gRPC TLS

#

# It is recommended to explicitly include a scheme. Leaving out the scheme

5039

# may cause constrasting behaviors across platforms.

5040

#

5041

# If the port is unspecified, the default is:

5042

# - 80 for schemes without TLS

5043

# - 443 for schemes with TLS

5044

#

5045

# For HTTP backends, use protocol

5046

# to specify the protocol version.

5047

"pathTranslation": "A String",

5048

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

5049

# This ID token will be added in the HTTP "authorization" header, and sent

5050

# to the backend.

5051

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

5052

# original "Authorization" HTTP header will be preserved. If the header is

5053

# used to carry the original token and is expected by the backend, this

5054

# field must be set to true to preserve the header.

5055

"renameTo": "A String", # Unimplemented. Do not use.

5056

#

5057

# The new name the selected proto elements should be renamed to.

5058

#

5059

# The package, the service and the method can all be renamed.

5060

# The backend server should implement the renamed proto. However, clients

5061

# should call the original method, and ESF routes the traffic to the renamed

5062

# method.

5063

#

5064

# HTTP clients should call the URL mapped to the original method.

5065

# gRPC and Stubby clients should call the original method with package name.

5066

#

5067

# For legacy reasons, ESF allows Stubby clients to call with the

5068

# short name (without the package name). However, for API Versioning(or

5069

# multiple methods mapped to the same short name), all Stubby clients must

5070

# call the method's full name with the package name, otherwise the first one

5071

# (selector) wins.

5072

#

5073

# If this `rename_to` is specified with a trailing `*`, the `selector` must

5074

# be specified with a trailing `*` as well. The all element short names

5075

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

5081

# rename_to: google.example.library.*

5082

#

5083

# The selector matches `google.example.library.v1.Library.CreateShelf` and

5084

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

5085

# `google.example.library.Library.CreateShelf` and

5086

# `google.example.library.Library.CreateBook`. It essentially renames the

5087

# proto package name section of the matched proto service and methods.

},

],

},

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5092

#

5093

# Example:

5094

# <pre><code>documentation:

5095

# summary: >

5096

# The Google Calendar API gives access

5097

# to most calendar features.

5098

# pages:

5099

# - name: Overview

5100

# content: &#40;== include google/foo/overview.md ==&#41;

5101

# - name: Tutorial

5102

# content: &#40;== include google/foo/tutorial.md ==&#41;

5103

# subpages;

5104

# - name: Java

5105

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

5106

# rules:

5107

# - selector: google.calendar.Calendar.Get

5108

# description: >

5109

# ...

5110

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5115

# standard markdown features, definition lists, tables and fenced

5116

# code blocks are supported. Section headers can be provided and are

5117

# interpreted relative to the section nesting of the context where

5118

# a documentation fragment is embedded.

5119

#

5120

# Documentation from the IDL is merged with documentation defined

5121

# via the config at normalization time, where documentation provided

5122

# by config rules overrides IDL provided.

5123

#

5124

# A number of constructs specific to the API platform are supported

5125

# in documentation text.

5126

#

5127

# In order to reference a proto element, the following

5128

# notation can be used:

5129

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

5130

# To override the display text used for the link, this can be used:

5131

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

5132

# Text can be excluded from doc using the following notation:

5133

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

5134

#

5135

# A few directives are available in documentation. Note that

5136

# directives must appear on a single line to be properly

5137

# identified. The `include` directive includes a markdown file from

5138

# an external source:

5139

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

5140

# The `resource_for` directive marks a message to be the resource of

5141

# a collection in REST view. If it is not specified, tools attempt

5142

# to infer the resource from the operations in a collection:

5143

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

5144

# The directive `suppress_warning` does not directly affect documentation

5145

# and is documented together with service config validation.

5146

"documentationRootUrl": "A String", # The URL to the root of documentation.

5147

"rules": [ # A list of documentation rules that apply to individual API elements.

5148

#

5149

# **NOTE:** All service configuration rules follow "last one wins" order.

5150

{ # A documentation rule provides information about individual API elements.

5151

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

5152

# an element is marked as `deprecated`.

5153

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5154

# qualified name of the element which may end in "*", indicating a wildcard.

5155

# Wildcards are only allowed at the end and for a whole component of the

5156

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

5157

# wildcard will match one or more components. To specify a default for all

5158

# applicable elements, the whole pattern "*" is used.

5159

"description": "A String", # Description of the selected API(s).

5160

},

5161

],

5162

"summary": "A String", # A short summary of what the service does. Can only be provided by

5163

# plain text.

5164

"overview": "A String", # Declares a single overview page. For example:

5165

# <pre><code>documentation:

5166

# summary: ...

5167

# overview: &#40;== include overview.md ==&#41;

5168

# </code></pre>

5169

# This is a shortcut for the following declaration (using pages style):

5170

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

5175

# </code></pre>

5176

# Note: you cannot specify both `overview` field and `pages` field.

5177

"pages": [ # The top level pages for the documentation set.

5178

{ # Represents a documentation page. A page can contain subpages to represent

5179

# nested documentation set structure.

5180

"name": "A String", # The name of the page. It will be used as an identity of the page to

5181

# generate URI of the page, text of the link to this page in navigation,

5182

# etc. The full page name (start from the root page name to this page

5183

# concatenated with `.`) can be used as reference to the page in your

5184

# documentation. For example:

5185

# <pre><code>pages:

5186

# - name: Tutorial

5187

# content: &#40;== include tutorial.md ==&#41;

5188

# subpages:

5189

# - name: Java

5190

# content: &#40;== include tutorial_java.md ==&#41;

5191

# </code></pre>

5192

# You can reference `Java` page using Markdown reference link syntax:

5193

# `Java`.

5194

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

5195

# ==&#41;</code> to include content from a Markdown file.

5196

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5197

# honored in the generated docset.

5198

# Object with schema name: Page

],

},

],

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

5203

# from the yaml file) is not suitable. This can be seen in any fully

5204

# specified service urls as well as sections that show a base that other

5205

# urls are relative to.

5206

},

5207

"logging": { # Logging configuration of the service. # Logging configuration.

5208

#

5209

# The following example shows how to configure logs to be sent to the

5210

# producer and consumer projects. In the example, the `activity_history`

5211

# log is sent to both the producer and consumer projects, whereas the

5212

# `purchase_history` log is only sent to the producer project.

5213

#

5214

# monitored_resources:

5215

# - type: library.googleapis.com/branch

5216

# labels:

5217

# - key: /city

5218

# description: The city where the library branch is located in.

5219

# - key: /name

5220

# description: The name of the branch.

5221

# logs:

5222

# - name: activity_history

5223

# labels:

5224

# - key: /customer_id

5225

# - name: purchase_history

5226

# logging:

5227

# producer_destinations:

5228

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

5233

# - monitored_resource: library.googleapis.com/branch

5234

# logs:

5235

# - activity_history

5236

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5237

# There can be multiple producer destinations, each one must have a

5238

# different monitored resource type. A log can be used in at most

5239

# one producer destination.

5240

{ # Configuration of a specific logging destination (the producer project

5241

# or the consumer project).

5242

"logs": [ # Names of the logs to be sent to this destination. Each name must

5243

# be defined in the Service.logs section. If the log name is

5244

# not a domain scoped name, it will be automatically prefixed with

5245

# the service name followed by "/".

5246

"A String",

5247

],

5248

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

5249

# Service.monitored_resources section.

5250

},

5251

],

5252

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5253

# There can be multiple consumer destinations, each one must have a

5254

# different monitored resource type. A log can be used in at most

5255

# one consumer destination.

5256

{ # Configuration of a specific logging destination (the producer project

5257

# or the consumer project).

5258

"logs": [ # Names of the logs to be sent to this destination. Each name must

5259

# be defined in the Service.logs section. If the log name is

5260

# not a domain scoped name, it will be automatically prefixed with

5261

# the service name followed by "/".

5262

"A String",

5263

],

5264

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

5265

# Service.monitored_resources section.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5270

# by the Service.monitoring and Service.logging configurations.

5271

{ # An object that describes the schema of a MonitoredResource object using a

5272

# type name and a set of labels. For example, the monitored resource

5273

# descriptor for Google Compute Engine VM instances has a type of

5274

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5275

# `"zone"` to identify particular VM instances.

5276

#

5277

# Different APIs can support different monitored resource types. APIs generally

5278

# provide a `list` method that returns the monitored resource descriptors used

5279

# by the API.

5280

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5281

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5282

# without any article or other determiners. For example,

5283

# `"Google Cloud SQL Database"`.

5284

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5285

# be used in documentation.

5286

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

5287

"labels": [ # Required. A set of labels used to describe instances of this monitored

5288

# resource type. For example, an individual Google Cloud SQL database is

5289

# identified by values for the labels `"database_id"` and `"zone"`.

5290

{ # A description of a label.

5291

"key": "A String", # The label key.

5292

"description": "A String", # A human-readable description for the label.

5293

"valueType": "A String", # The type of data that can be assigned to the label.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5294

},

5295

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5296

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5297

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5298

# {type} is the value of the `type` field in this object and

5299

# {project_id} is a project ID that provides API-specific context for

5300

# accessing the type. APIs that do not use project information can use the

5301

# resource name format `"monitoredResourceDescriptors/{type}"`.

5302

"type": "A String", # Required. The monitored resource type. For example, the type

5303

# `"cloudsql_database"` represents databases in Google Cloud SQL.

5304

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5305

},

5306

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5307

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5308

#

5309

# Example:

5310

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

5316

# - google.rpc.context.OriginContext

5317

#

5318

# The above specifies that all methods in the API request

5319

# `google.rpc.context.ProjectContext` and

5320

# `google.rpc.context.OriginContext`.

5321

#

5322

# Available context types are defined in package

5323

# `google.rpc.context`.

5324

#

5325

# This also provides mechanism to whitelist any protobuf message extension that

5326

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

5327

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

5328

# specific protobuf types that can appear in grpc metadata as follows in your

# yaml file:

#

# Example:

#

# context:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

5336

# allowed_request_extensions:

5337

# - google.foo.v1.NewExtension

5338

# allowed_response_extensions:

5339

# - google.foo.v1.NewExtension

5340

#

5341

# You can also specify extension ID instead of fully qualified extension name

5342

# here.

5343

"rules": [ # A list of RPC context rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5344

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5345

# **NOTE:** All service configuration rules follow "last one wins" order.

5346

{ # A context rule provides information about the context for an individual API

5347

# element.

5348

"requested": [ # A list of full type names of requested contexts.

5349

"A String",

5350

],

5351

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5352

# side channel from client to backend.

5353

"A String",

5354

],

5355

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5356

# side channel from backend to client.

5357

"A String",

5358

],

5359

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5360

#

5361

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5362

"provided": [ # A list of full type names of provided contexts.

5363

"A String",

5364

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5365

},

5366

],

5367

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5368

"enums": [ # A list of all enum types included in this API service. Enums

5369

# referenced directly or indirectly by the `apis` are automatically

5370

# included. Enums which are not referenced but shall be included

5371

# should be listed here by name. Example:

5372

#

5373

# enums:

5374

# - name: google.someapi.v1.SomeEnum

5375

{ # Enum type definition.

5376

"name": "A String", # Enum type name.

5377

"enumvalue": [ # Enum value definitions.

5378

{ # Enum value definition.

5379

"name": "A String", # Enum value name.

5380

"options": [ # Protocol buffer options.

5381

{ # A protocol buffer option, which can be attached to a message, field,

5382

# enumeration, etc.

5383

"value": { # The option's value packed in an Any message. If the value is a primitive,

5384

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5385

# should be used. If the value is an enum, it should be stored as an int32

5386

# value using the google.protobuf.Int32Value type.

5387

"a_key": "", # Properties of the object. Contains field @type with type URL.

5388

},

5389

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5390

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5391

# For custom options, it should be the fully-qualified name. For example,

5392

# `"google.api.http"`.

5393

},

5394

],

5395

"number": 42, # Enum value number.

5396

},

5397

],

5398

"options": [ # Protocol buffer options.

5399

{ # A protocol buffer option, which can be attached to a message, field,

5400

# enumeration, etc.

5401

"value": { # The option's value packed in an Any message. If the value is a primitive,

5402

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5403

# should be used. If the value is an enum, it should be stored as an int32

5404

# value using the google.protobuf.Int32Value type.

5405

"a_key": "", # Properties of the object. Contains field @type with type URL.

5406

},

5407

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5408

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5409

# For custom options, it should be the fully-qualified name. For example,

5410

# `"google.api.http"`.

5411

},

5412

],

5413

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5414

# protobuf element, like the file in which it is defined.

5415

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5416

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5417

},

5418

"syntax": "A String", # The source syntax.

5419

},

5420

],

5421

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5422

# by the client for tracking purpose. Must be no longer than 63 characters

5423

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

5424

# empty, the server may choose to generate one instead.

5425

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

5426

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

5427

# service producer.

5428

#

5429

# Google Service Management currently only supports

5430

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

5431

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

5432

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

5433

# documented in https://cloud.google.com/pubsub/docs/overview.

5434

"rules": [ # A list of usage rules that apply to individual API methods.

5435

#

5436

# **NOTE:** All service configuration rules follow "last one wins" order.

5437

{ # Usage configuration rules for the service.

5438

#

5439

# NOTE: Under development.

5440

#

5441

#

5442

# Use this rule to configure unregistered calls for the service. Unregistered

5443

# calls are calls that do not contain consumer project identity.

5444

# (Example: calls that do not contain an API key).

5445

# By default, API methods do not allow unregistered calls, and each method call

5446

# must be identified by a consumer project identity. Use this rule to

5447

# allow/disallow unregistered calls.

5448

#

5449

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

5455

#

5456

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

5461

# allow_unregistered_calls: true

5462

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5463

# methods in all APIs.

5464

#

5465

# Refer to selector for syntax details.

5466

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

5467

# plane features, such as quota and billing, will not be available.

5468

# This flag is used by Google Cloud Endpoints to bypass checks for internal

5469

# methods, such as service health check methods.

5470

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

5471

# that don't identify any user or application.

5472

},

5473

],

5474

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

5475

#

5476

#

5477

# Use this field to configure per-product per-project service identity.

5478

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

5483

# display_name: "Cloud XXX Service Agent"

5484

# description: "Used as the identity of Cloud XXX to access resources"

5485

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

5486

#

5487

# An example name would be:

5488

# `projects/123456789`

5489

"displayName": "A String", # Optional. A user-specified name for the service account.

5490

# Must be less than or equal to 100 UTF-8 bytes.

5491

"description": "A String", # Optional. A user-specified opaque description of the service account.

5492

# Must be less than or equal to 256 UTF-8 bytes.

5493

},

5494

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

5495

# service. Each requirement is of the form <service.name>/<requirement-id>;

5496

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5501

{ # Defines a metric type and its schema. Once a metric descriptor is created,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5502

# deleting or altering it stops data collection and makes the metric type's

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5503

# existing data unusable.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5504

"name": "A String", # The resource name of the metric descriptor.

5505

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5506

# URL-encoded. All user-defined metric types have the DNS name

5507

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

5508

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5509

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5510

# "custom.googleapis.com/invoice/paid/amount"

5511

# "external.googleapis.com/prometheus/up"

5512

# "appengine.googleapis.com/http/server/response_latencies"

5513

"metadata": { # Additional annotations that can be used to guide the usage of a metric. # Optional. Metadata which can be used to guide usage of the metric.

5514

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

5515

# age are guaranteed to be ingested and available to be read, excluding

5516

# data loss due to errors.

5517

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

5518

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

5519

# periodically, consecutive data points are stored at this time interval,

5520

# excluding data loss due to errors. Metrics with a higher granularity have

5521

# a smaller sampling period.

5522

},

5523

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

5524

# Some combinations of `metric_kind` and `value_type` might not be supported.

5525

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

5526

# Some combinations of `metric_kind` and `value_type` might not be supported.

5527

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5528

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5529

# Use sentence case without an ending period, for example "Request count".

5530

# This field is optional but it is recommended to be set for any metrics

5531

# associated with user-visible concepts, such as Quota.

5532

"unit": "A String", # The units in which the metric value is reported. It is only applicable

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5533

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

5534

# defines the representation of the stored metric values.

5535

#

5536

# Different systems may scale the values to be more easily displayed (so a

5537

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

5538

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

5539

# `KBy`, then the value of the metric is always in thousands of bytes, no

5540

# matter how it may be displayed..

5541

#

5542

# If you want a custom metric to record the exact number of CPU-seconds used

5543

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

5544

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

5545

# CPU-seconds, then the value is written as `12005`.

5546

#

5547

# Alternatively, if you want a custom metric to record data in a more

5548

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

5549

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

5550

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

5551

#

5552

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5553

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5554

#

5555

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

5565

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

5573

# * `Y` yotta (10^24)

5574

#

5575

# * `m` milli (10^-3)

5576

# * `u` micro (10^-6)

5577

# * `n` nano (10^-9)

5578

# * `p` pico (10^-12)

5579

# * `f` femto (10^-15)

5580

# * `a` atto (10^-18)

5581

# * `z` zepto (10^-21)

5582

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5589

#

5590

# **Grammar**

5591

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5592

# The grammar also includes these connectors:

5593

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5594

# * `/` division or ratio (as an infix operator). For examples,

5595

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

5596

# have `/s` in a metric `unit`; rates should always be computed at

5597

# query time from the underlying cumulative or delta value).

5598

# * `.` multiplication or composition (as an infix operator). For

5599

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5600

#

5601

# The grammar for a unit is as follows:

5602

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5603

# Expression = Component { "." Component } { "/" Component } ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5604

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5605

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5606

# | Annotation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5607

# | "1"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5608

# ;

5609

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5610

# Annotation = "{" NAME "}" ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5611

#

5612

# Notes:

5613

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5614

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

5615

# is used alone, then the unit is equivalent to `1`. For examples,

5616

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5617

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5618

# containing `{` or `}`.

5619

# * `1` represents a unitary [dimensionless

5620

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

5621

# as in `1/s`. It is typically used when none of the basic units are

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5622

# appropriate. For example, "new users per day" can be represented as

5623

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

5624

# users). Alternatively, "thousands of page views per day" would be

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5625

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5626

# value of `5.3` would mean "5300 page views per day").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5627

# * `%` represents dimensionless value of 1/100, and annotates values giving

5628

# a percentage (so the metric values are typically in the range of 0..100,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5629

# and a metric value `3` means "3 percent").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5630

# * `10^2.%` indicates a metric contains a ratio, typically in the range

5631

# 0..1, that will be multiplied by 100 and displayed as a percentage

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5632

# (so a metric value `0.03` means "3 percent").

5633

"monitoredResourceTypes": [ # Read-only. If present, then a time

5634

# series, which is identified partially by

5635

# a metric type and a MonitoredResourceDescriptor, that is associated

5636

# with this metric type can only be associated with one of the monitored

5637

# resource types listed here.

5638

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5639

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5640

"launchStage": "A String", # Optional. The launch stage of the metric definition.

5641

"labels": [ # The set of labels that can be used to describe a specific

5642

# instance of this metric type. For example, the

5643

# `appengine.googleapis.com/http/server/response_latencies` metric

5644

# type has a label for the HTTP response code, `response_code`, so

5645

# you can look at latencies for successful responses or just

5646

# for responses that failed.

5647

{ # A description of a label.

5648

"key": "A String", # The label key.

5649

"description": "A String", # A human-readable description for the label.

5650

"valueType": "A String", # The type of data that can be assigned to the label.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5651

},

5652

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5653

},

5654

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5655

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5656

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5657

# Example for an API targeted for external use:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5658

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5659

# name: calendar.googleapis.com

5660

# authentication:

5661

# providers:

5662

# - id: google_calendar_auth

5663

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5664

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5665

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5666

# - selector: "*"

5667

# requirements:

5668

# provider_id: google_calendar_auth

5669

"rules": [ # A list of authentication rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5670

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5671

# **NOTE:** All service configuration rules follow "last one wins" order.

5672

{ # Authentication rules for the service.

5673

#

5674

# By default, if a method has any authentication requirements, every request

5675

# must include a valid credential matching one of the requirements.

5676

# It's an error to include more than one kind of credential in a single

5677

# request.

5678

#

5679

# If a method doesn't have any auth requirements, request credentials will be

5680

# ignored.

5681

"requirements": [ # Requirements for additional authentication providers.

5682

{ # User-defined authentication requirements, including support for

5683

# [JSON Web Token

5684

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5685

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

5690

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

5691

# implemented and accepted in all the runtime components.

5692

#

5693

# The list of JWT

5694

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5695

# that are allowed to access. A JWT containing any of these audiences will

5696

# be accepted. When this setting is absent, only JWTs with audience

5697

# "https://Service_name/API_name"

5698

# will be accepted. For example, if no audiences are in the setting,

5699

# LibraryService API will only accept JWTs with the following audience

5700

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5705

# bookstore_web.apps.googleusercontent.com

5706

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5707

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5708

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5709

#

5710

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5711

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

5712

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

5713

# there are scopes defined for "Read-only access to Google Calendar" and

5714

# "Access to Cloud Platform". Users can consent to a scope for an application,

5715

# giving it permission to access that data on their behalf.

5716

#

5717

# OAuth scope specifications should be fairly coarse grained; a user will need

5718

# to see and understand the text description of what your scope means.

5719

#

5720

# In most cases: use one or at most two OAuth scopes for an entire family of

5721

# products. If your product has multiple APIs, you should probably be sharing

5722

# the OAuth scope across all of those APIs.

5723

#

5724

# When you need finer grained OAuth consent screens: talk with your product

5725

# management about how developers will use them in practice.

5726

#

5727

# Please note that even though each of the canonical scopes is enough for a

5728

# request to be accepted and passed to the backend, a request can still fail

5729

# due to the backend requiring additional scopes or permissions.

5730

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

5731

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

5736

# https://www.googleapis.com/auth/calendar.read

},

},

],

"providers": [ # Defines a set of authentication providers that a service supports.

5741

{ # Configuration for an authentication provider, including support for

5742

# [JSON Web Token

5743

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5744

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

5745

# [OpenID

5746

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

5747

# Optional if the key set document:

5748

# - can be retrieved from

5749

# [OpenID

5750

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

5751

# the issuer.

5752

# - can be inferred from the email domain of the issuer (e.g. a Google

5753

# service account).

5754

#

5755

# Example: https://www.googleapis.com/oauth2/v1/certs

5756

"audiences": "A String", # The list of JWT

5757

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5758

# that are allowed to access. A JWT containing any of these audiences will

5759

# be accepted. When this setting is absent, JWTs with audiences:

5760

# - "https://[service.name]/[google.protobuf.Api.name]"

5761

# - "https://[service.name]/"

5762

# will be accepted.

5763

# For example, if no audiences are in the setting, LibraryService API will

5764

# accept JWTs with the following audiences:

5765

# -

5766

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

5767

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5772

# bookstore_web.apps.googleusercontent.com

5773

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

5774

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

5775

"issuer": "A String", # Identifies the principal that issued the JWT. See

5776

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

5777

# Usually a URL or an email address.

5778

#

5779

# Example: https://securetoken.google.com

5780

# Example: 1234567-compute@developer.gserviceaccount.com

5781

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

5782

# `AuthRequirement.provider_id`.

5783

#

5784

# Example: "bookstore_auth".

5785

"jwtLocations": [ # Defines the locations to extract the JWT.

5786

#

5787

# JWT locations can be either from HTTP headers or URL query parameters.

5788

# The rule is that the first match wins. The checking order is: checking

5789

# all headers first, then URL query parameters.

5790

#

5791

# If not specified, default to use following 3 locations:

5792

# 1) Authorization: Bearer

5793

# 2) x-goog-iap-jwt-assertion

5794

# 3) access_token query parameter

5795

#

5796

# Default locations can be specified as followings:

5797

# jwt_locations:

5798

# - header: Authorization

5799

# value_prefix: "Bearer "

5800

# - header: x-goog-iap-jwt-assertion

5801

# - query: access_token

5802

{ # Specifies a location to extract JWT from an API request.

5803

"header": "A String", # Specifies HTTP header name to extract JWT token.

5804

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

5805

# Only applies to "in" header type. Must be empty for "in" query type.

5806

# If not empty, the header value has to match (case sensitive) this prefix.

5807

# If not matched, JWT will not be extracted. If matched, JWT will be

5808

# extracted after the prefix is removed.

5809

#

5810

# For example, for "Authorization: Bearer {JWT}",

5811

# value_prefix="Bearer " with a space at the end.

5812

"query": "A String", # Specifies URL query parameter name to extract JWT token.

5813

},

5814

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5815

},

5816

],

5817

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5818

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

5819

# service controller handles features like abuse, quota, billing, logging,

5820

# monitoring, etc.

5821

"environment": "A String", # The service control environment to use. If empty, no control plane

5822

# feature (like quota and billing) will be enabled.

5823

},

5824

"configVersion": 42, # The semantic version of the service configuration. The config version

5825

# affects the interpretation of the service configuration. For example,

5826

# certain features are enabled by default for certain config versions.

5827

#

5828

# The latest config version is `3`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5833

<code class="details" id="list">list(serviceName, pageToken=None, pageSize=None, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5834

<pre>Lists the history of the service configuration for a managed service,

5835

from the newest to the oldest.

5836

5837

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5838

serviceName: string, Required. The name of the service. See the [overview](/service-management/overview)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5839

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5840

pageToken: string, The token of the page to retrieve.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5841

pageSize: integer, The max number of items to include in the response list. Page size is 50

5842

if not specified. Maximum value is 100.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5843

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5850

5851

{ # Response message for ListServiceConfigs method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5852

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5853

{ # `Service` is the root object of Google service configuration schema. It

5854

# describes basic information about a service, such as the name and the

5855

# title, and delegates other aspects to sub-sections. Each sub-section is

5856

# either a proto message or a repeated proto message that configures a

5857

# specific aspect, such as auth. See each proto message definition for details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

#

# Example:

#

# type: google.api.Service

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5862

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5863

# name: calendar.googleapis.com

5864

# title: Google Calendar API

5865

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5866

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5867

# authentication:

5868

# providers:

5869

# - id: google_calendar_auth

5870

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5871

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5872

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5873

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5874

# requirements:

5875

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5876

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5877

#

5878

# The example below shows how to configure monitored resources and metrics

5879

# for monitoring. In the example, a monitored resource and two metrics are

5880

# defined. The `library.googleapis.com/book/returned_count` metric is sent

5881

# to both producer and consumer projects, whereas the

5882

# `library.googleapis.com/book/overdue_count` metric is only sent to the

5883

# consumer project.

5884

#

5885

# monitored_resources:

5886

# - type: library.googleapis.com/branch

5887

# labels:

5888

# - key: /city

5889

# description: The city where the library branch is located in.

5890

# - key: /name

5891

# description: The name of the branch.

5892

# metrics:

5893

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

5898

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

5903

# monitoring:

5904

# producer_destinations:

5905

# - monitored_resource: library.googleapis.com/branch

5906

# metrics:

5907

# - library.googleapis.com/book/returned_count

5908

# consumer_destinations:

5909

# - monitored_resource: library.googleapis.com/branch

5910

# metrics:

5911

# - library.googleapis.com/book/returned_count

5912

# - library.googleapis.com/book/overdue_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5913

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5914

# There can be multiple consumer destinations. A monitored resouce type may

5915

# appear in multiple monitoring destinations if different aggregations are

5916

# needed for different sets of metrics associated with that monitored

5917

# resource type. A monitored resource and metric pair may only be used once

5918

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5919

{ # Configuration of a specific monitoring destination (the producer project

5920

# or the consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5921

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5922

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5923

"metrics": [ # Types of the metrics to report to this monitoring destination.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5924

# Each type must be defined in Service.metrics section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

"A String",

],

},

],

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

5930

# There can be multiple producer destinations. A monitored resouce type may

5931

# appear in multiple monitoring destinations if different aggregations are

5932

# needed for different sets of metrics associated with that monitored

5933

# resource type. A monitored resource and metric pair may only be used once

5934

# in the Monitoring configuration.

5935

{ # Configuration of a specific monitoring destination (the producer project

5936

# or the consumer project).

5937

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5938

# Service.monitored_resources section.

5939

"metrics": [ # Types of the metrics to report to this monitoring destination.

5940

# Each type must be defined in Service.metrics section.

5941

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

],

},

],

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5946

"systemTypes": [ # A list of all proto message types included in this API service.

5947

# It serves similar purpose as [google.api.Service.types], except that

5948

# these types are not needed by user-defined APIs. Therefore, they will not

5949

# show up in the generated discovery doc. This field should only be used

5950

# to define system APIs in ESF.

5951

{ # A protocol buffer message type.

5952

"options": [ # The protocol buffer options.

5953

{ # A protocol buffer option, which can be attached to a message, field,

5954

# enumeration, etc.

5955

"value": { # The option's value packed in an Any message. If the value is a primitive,

5956

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5957

# should be used. If the value is an enum, it should be stored as an int32

5958

# value using the google.protobuf.Int32Value type.

5959

"a_key": "", # Properties of the object. Contains field @type with type URL.

5960

},

5961

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5962

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5963

# For custom options, it should be the fully-qualified name. For example,

5964

# `"google.api.http"`.

5965

},

5966

],

5967

"fields": [ # The list of fields.

5968

{ # A single field of a message type.

5969

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5970

"name": "A String", # The field name.

5971

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5972

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5973

"number": 42, # The field number.

5974

"kind": "A String", # The field type.

5975

"jsonName": "A String", # The field JSON name.

5976

"options": [ # The protocol buffer options.

5977

{ # A protocol buffer option, which can be attached to a message, field,

5978

# enumeration, etc.

5979

"value": { # The option's value packed in an Any message. If the value is a primitive,

5980

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5981

# should be used. If the value is an enum, it should be stored as an int32

5982

# value using the google.protobuf.Int32Value type.

5983

"a_key": "", # Properties of the object. Contains field @type with type URL.

5984

},

5985

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5986

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5987

# For custom options, it should be the fully-qualified name. For example,

5988

# `"google.api.http"`.

5989

},

5990

],

5991

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5992

# types. The first type has index 1; zero means the type is not in the list.

5993

"packed": True or False, # Whether to use alternative packed wire representation.

5994

"cardinality": "A String", # The field cardinality.

5995

},

5996

],

5997

"name": "A String", # The fully qualified message name.

5998

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5999

"A String",

6000

],

6001

"syntax": "A String", # The source syntax.

6002

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6003

# protobuf element, like the file in which it is defined.

6004

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6005

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"producerProjectId": "A String", # The Google project that owns this service.

6010

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

6011

# usage.

6012

#

6013

# The metric based quota configuration works this way:

6014

# - The service configuration defines a set of metrics.

6015

# - For API calls, the quota.metric_rules maps methods to metrics with

6016

# corresponding costs.

6017

# - The quota.limits defines limits on the metrics, which will be used for

6018

# quota checks at runtime.

6019

#

6020

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

6026

# metric: library.googleapis.com/write_calls

6027

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

6033

# # except for the UpdateBook and DeleteBook methods. These two methods

6034

# # are mapped to the write_calls metric, with the UpdateBook method

6035

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

6040

# - selector: google.example.library.v1.LibraryService.UpdateBook

6041

# metric_costs:

6042

# library.googleapis.com/write_calls: 2

6043

# - selector: google.example.library.v1.LibraryService.DeleteBook

6044

# metric_costs:

6045

# library.googleapis.com/write_calls: 1

6046

#

6047

# Corresponding Metric definition:

6048

#

6049

# metrics:

6050

# - name: library.googleapis.com/read_calls

6051

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

6056

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

6061

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

6062

# for a limit type. There can be at most one limit for a duration and limit

6063

# type combination defined within a `QuotaGroup`.

6064

"name": "A String", # Name of the quota limit.

6065

#

6066

# The name must be provided, and it must be unique within the service. The

6067

# name can only include alphanumeric characters as well as '-'.

6068

#

6069

# The maximum length of the limit name is 64 characters.

6070

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

6071

# The free tier is the number of tokens that will be subtracted from the

6072

# billed amount when billing is enabled.

6073

# This field can only be set on a limit with duration "1d", in a billable

6074

# group; it is invalid on any other limit. If this field is not set, it

6075

# defaults to 0, indicating that there is no free tier for this service.

6076

#

6077

# Used by group-based quotas only.

6078

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

6079

#

6080

# Used by group-based quotas only.

6081

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

6082

# duration. This is the number of tokens assigned when a client

6083

# application developer activates the service for his/her project.

6084

#

6085

# Specifying a value of 0 will block all requests. This can be used if you

6086

# are provisioning quota to selected consumers and blocking others.

6087

# Similarly, a value of -1 will indicate an unlimited quota. No other

6088

# negative values are allowed.

6089

#

6090

# Used by group-based quotas only.

6091

"description": "A String", # Optional. User-visible, extended description for this quota limit.

6092

# Should be used only when more context is needed to understand this limit

6093

# than provided by the limit's display name (see: `display_name`).

6094

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

6095

# the same metric will be checked together during runtime. The metric must be

6096

# defined within the service config.

6097

"displayName": "A String", # User-visible display name for this limit.

6098

# Optional. If not set, the UI will provide a default display name based on

6099

# the quota configuration. This field can be used to override the default

6100

# display name generated from the configuration.

6101

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

6102

# integer value that is the maximum number of requests allowed for the

6103

# specified unit. Currently only STANDARD is supported.

6104

"a_key": "A String",

6105

},

6106

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

6107

# Metric.unit. The supported unit kinds are determined by the quota

6108

# backend system.

6109

#

6110

# Here are some examples:

6111

# * "1/min/{project}" for quota per minute per project.

6112

#

6113

# Note: the order of unit components is insignificant.

6114

# The "1" at the beginning is required to follow the metric unit syntax.

6115

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

6116

# duration. Client application developers can override the default limit up

6117

# to this maximum. If specified, this value cannot be set to a value less

6118

# than the default limit. If not specified, it is set to the default limit.

6119

#

6120

# To allow clients to apply overrides with no upper bound, set this to -1,

6121

# indicating unlimited maximum quota.

6122

#

6123

# Used by group-based quotas only.

6124

},

6125

],

6126

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

6127

# or more metrics.

6128

{ # Bind API methods to metrics. Binding a method to a metric causes that

6129

# metric's configured quota behaviors to apply to the method call.

6130

"selector": "A String", # Selects the methods to which this rule applies.

6131

#

6132

# Refer to selector for syntax details.

6133

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

6134

# cost applied to each metric.

6135

#

6136

# The key of the map is the metric name, and the values are the amount

6137

# increased for the metric against which the quota limits are defined.

6138

# The value must not be negative.

"a_key": "A String",

},

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

6145

# service, such as `calendar.googleapis.com`. The service name

6146

# typically goes through DNS verification to make sure the owner

6147

# of the service also owns the DNS name.

6148

"billing": { # Billing related configuration of the service. # Billing configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6149

#

6150

# The following example shows how to configure monitored resources and metrics

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6151

# for billing, `consumer_destinations` is the only supported destination and

6152

# the monitored resources need at least one label key

6153

# `cloud.googleapis.com/location` to indicate the location of the billing

6154

# usage, using different monitored resources between monitoring and billing is

6155

# recommended so they can be evolved independently:

6156

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6157

#

6158

# monitored_resources:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6159

# - type: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6160

# labels:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6161

# - key: cloud.googleapis.com/location

6162

# description: |

6163

# Predefined label to support billing location restriction.

6164

# - key: city

6165

# description: |

6166

# Custom label to define the city where the library branch is located

6167

# in.

6168

# - key: name

6169

# description: Custom label to define the name of the library branch.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6170

# metrics:

6171

# - name: library.googleapis.com/book/borrowed_count

6172

# metric_kind: DELTA

6173

# value_type: INT64

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6174

# unit: "1"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6175

# billing:

6176

# consumer_destinations:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6177

# - monitored_resource: library.googleapis.com/billing_branch

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6178

# metrics:

6179

# - library.googleapis.com/book/borrowed_count

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6180

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6181

# There can be multiple consumer destinations per service, each one must have

6182

# a different monitored resource type. A metric can be used in at most

6183

# one consumer destination.

6184

{ # Configuration of a specific billing destination (Currently only support

6185

# bill against consumer project).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6186

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6187

# Service.monitored_resources section.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6188

"metrics": [ # Names of the metrics to report to this billing destination.

6189

# Each name must be defined in Service.metrics section.

6190

"A String",

6191

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6192

},

6193

],

6194

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6195

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

6196

# specific protobuf types that can appear in error detail lists of

6197

# error responses.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6198

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6199

# Example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6200

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6201

# custom_error:

6202

# types:

6203

# - google.foo.v1.CustomError

6204

# - google.foo.v1.AnotherError

6205

"rules": [ # The list of custom error rules that apply to individual API messages.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6206

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6207

# **NOTE:** All service configuration rules follow "last one wins" order.

6208

{ # A custom error rule.

6209

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

6210

# objects of this type will be filtered when they appear in error payload.

6211

"selector": "A String", # Selects messages to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6212

#

6213

# Refer to selector for syntax details.

6214

},

6215

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6216

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

6217

"A String",

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6218

],

6219

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6220

"title": "A String", # The product title for this service.

6221

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

6222

# with the same name as the service is automatically generated to service all

6223

# defined APIs.

6224

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

6225

# A service may expose any number of endpoints, and all endpoints share the

6226

# same service configuration, such as quota configuration and monitoring

6227

# configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6228

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6229

# Example service configuration:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6230

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6231

# name: library-example.googleapis.com

6232

# endpoints:

6233

# # Below entry makes 'google.example.library.v1.Library'

6234

# # API be served from endpoint address library-example.googleapis.com.

6235

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

6236

# # it to decide whether the subsequent cross-origin request is

6237

# # allowed to proceed.

6238

# - name: library-example.googleapis.com

6239

# allow_cors: true

6240

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

6241

# please specify multiple google.api.Endpoint for each of the intended

6242

# aliases.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6243

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6244

# Additional names that this endpoint will be hosted on.

6245

"A String",

6246

],

6247

"features": [ # The list of features enabled on this endpoint.

6248

"A String",

6249

],

6250

"allowCors": True or False, # Allowing

6251

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

6252

# cross-domain traffic, would allow the backends served from this endpoint to

6253

# receive and respond to HTTP OPTIONS requests. The response will be used by

6254

# the browser to determine whether the subsequent cross-origin request is

6255

# allowed to proceed.

6256

"name": "A String", # The canonical name of this endpoint.

6257

"target": "A String", # The specification of an Internet routable address of API frontend that will

6258

# handle requests to this [API

6259

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

6260

# either a valid IPv4 address or a fully-qualified domain name. For example,

6261

# "8.8.8.8" or "myservice.appspot.com".

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6262

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6263

],

6264

"logs": [ # Defines the logs used by this service.

6265

{ # A description of a log type. Example in YAML format:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6266

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6267

# - name: library.googleapis.com/activity_history

6268

# description: The history of borrowing and returning library items.

6269

# display_name: Activity

6270

# labels:

6271

# - key: /customer_id

6272

# description: Identifier of a library customer

6273

"labels": [ # The set of labels that are available to describe a specific log entry.

6274

# Runtime requests that contain labels not specified here are

6275

# considered invalid.

6276

{ # A description of a label.

6277

"key": "A String", # The label key.

6278

"description": "A String", # A human-readable description for the label.

6279

"valueType": "A String", # The type of data that can be assigned to the label.

6280

},

6281

],

6282

"name": "A String", # The name of the log. It must be less than 512 characters long and can

6283

# include the following characters: upper- and lower-case alphanumeric

6284

# characters [A-Za-z0-9], and punctuation characters including

6285

# slash, underscore, hyphen, period [/_-.].

6286

"description": "A String", # A human-readable description of this log. This information appears in

6287

# the documentation and can contain details.

6288

"displayName": "A String", # The human-readable name for this log. This information appears on

6289

# the user interface and should be concise.

6290

},

6291

],

6292

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

6293

# of the google.protobuf.Api needs to be provided by the configuration

6294

# author, as the remaining fields will be derived from the IDL during the

6295

# normalization process. It is an error to specify an API interface here

6296

# which cannot be resolved against the associated IDL files.

6297

{ # Api is a light-weight descriptor for an API Interface.

6298

#

6299

# Interfaces are also described as "protocol buffer services" in some contexts,

6300

# such as by the "service" keyword in a .proto file, but they are different

6301

# from API Services, which represent a concrete implementation of an interface

6302

# as opposed to simply a description of methods and bindings. They are also

6303

# sometimes simply referred to as "APIs" in other contexts, such as the name of

6304

# this message itself. See https://cloud.google.com/apis/design/glossary for

6305

# detailed terminology.

6306

"options": [ # Any metadata attached to the interface.

6307

{ # A protocol buffer option, which can be attached to a message, field,

6308

# enumeration, etc.

6309

"value": { # The option's value packed in an Any message. If the value is a primitive,

6310

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6311

# should be used. If the value is an enum, it should be stored as an int32

6312

# value using the google.protobuf.Int32Value type.

6313

"a_key": "", # Properties of the object. Contains field @type with type URL.

6314

},

6315

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6316

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6317

# For custom options, it should be the fully-qualified name. For example,

6318

# `"google.api.http"`.

6319

},

6320

],

6321

"methods": [ # The methods of this interface, in unspecified order.

6322

{ # Method represents a method of an API interface.

6323

"responseTypeUrl": "A String", # The URL of the output message type.

6324

"options": [ # Any metadata attached to the method.

6325

{ # A protocol buffer option, which can be attached to a message, field,

6326

# enumeration, etc.

6327

"value": { # The option's value packed in an Any message. If the value is a primitive,

6328

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6329

# should be used. If the value is an enum, it should be stored as an int32

6330

# value using the google.protobuf.Int32Value type.

6331

"a_key": "", # Properties of the object. Contains field @type with type URL.

6332

},

6333

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6334

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6335

# For custom options, it should be the fully-qualified name. For example,

6336

# `"google.api.http"`.

6337

},

6338

],

6339

"responseStreaming": True or False, # If true, the response is streamed.

6340

"name": "A String", # The simple name of this method.

6341

"requestTypeUrl": "A String", # A URL of the input message type.

6342

"requestStreaming": True or False, # If true, the request is streamed.

6343

"syntax": "A String", # The source syntax of this method.

6344

},

6345

],

6346

"name": "A String", # The fully qualified name of this interface, including package name

6347

# followed by the interface's simple name.

6348

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

6349

# message.

6350

# protobuf element, like the file in which it is defined.

6351

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6352

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6353

},

6354

"syntax": "A String", # The source syntax of the service.

6355

"version": "A String", # A version string for this interface. If specified, must have the form

6356

# `major-version.minor-version`, as in `1.10`. If the minor version is

6357

# omitted, it defaults to zero. If the entire version field is empty, the

6358

# major version is derived from the package name, as outlined below. If the

6359

# field is not empty, the version in the package name will be verified to be

6360

# consistent with what is provided here.

6361

#

6362

# The versioning schema uses [semantic

6363

# versioning](http://semver.org) where the major version number

6364

# indicates a breaking change and the minor version an additive,

6365

# non-breaking change. Both version numbers are signals to users

6366

# what to expect from different versions, and should be carefully

6367

# chosen based on the product plan.

6368

#

6369

# The major version is also reflected in the package name of the

6370

# interface, which must end in `v<major-version>`, as in

6371

# `google.feature.v1`. For major versions 0 and 1, the suffix can

6372

# be omitted. Zero major versions must only be used for

6373

# experimental, non-GA interfaces.

6374

"mixins": [ # Included interfaces. See Mixin.

6375

{ # Declares an API Interface to be included in this interface. The including

6376

# interface must redeclare all the methods from the included interface, but

6377

# documentation and options are inherited as follows:

6378

#

6379

# - If after comment and whitespace stripping, the documentation

6380

# string of the redeclared method is empty, it will be inherited

6381

# from the original method.

6382

#

6383

# - Each annotation belonging to the service config (http,

6384

# visibility) which is not set in the redeclared method will be

6385

# inherited.

6386

#

6387

# - If an http annotation is inherited, the path pattern will be

6388

# modified as follows. Any version prefix will be replaced by the

6389

# version of the including interface plus the root path if

6390

# specified.

6391

#

6392

# Example of a simple mixin:

6393

#

6394

# package google.acl.v1;

6395

# service AccessControl {

6396

# // Get the underlying ACL object.

6397

# rpc GetAcl(GetAclRequest) returns (Acl) {

6398

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

6403

# service Storage {

6404

# // rpc GetAcl(GetAclRequest) returns (Acl);

6405

#

6406

# // Get a data record.

6407

# rpc GetData(GetDataRequest) returns (Data) {

6408

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

6413

#

6414

# apis:

6415

# - name: google.storage.v2.Storage

6416

# mixins:

6417

# - name: google.acl.v1.AccessControl

6418

#

6419

# The mixin construct implies that all methods in `AccessControl` are

6420

# also declared with same name and request/response types in

6421

# `Storage`. A documentation generator or annotation processor will

6422

# see the effective `Storage.GetAcl` method after inherting

6423

# documentation and annotations as follows:

6424

#

6425

# service Storage {

6426

# // Get the underlying ACL object.

6427

# rpc GetAcl(GetAclRequest) returns (Acl) {

6428

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

6434

#

6435

# If the `root` field in the mixin is specified, it should be a

6436

# relative path under which inherited HTTP paths are placed. Example:

6437

#

6438

# apis:

6439

# - name: google.storage.v2.Storage

6440

# mixins:

6441

# - name: google.acl.v1.AccessControl

6442

# root: acls

6443

#

6444

# This implies the following inherited HTTP annotation:

6445

#

6446

# service Storage {

6447

# // Get the underlying ACL object.

6448

# rpc GetAcl(GetAclRequest) returns (Acl) {

6449

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"name": "A String", # The fully qualified name of the interface which is included.

6454

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

# are rooted.

},

],

},

],

"types": [ # A list of all proto message types included in this API service.

6461

# Types referenced directly or indirectly by the `apis` are

6462

# automatically included. Messages which are not referenced but

6463

# shall be included, such as types used by the `google.protobuf.Any` type,

6464

# should be listed here by name. Example:

6465

#

6466

# types:

6467

# - name: google.protobuf.Int32

6468

{ # A protocol buffer message type.

6469

"options": [ # The protocol buffer options.

6470

{ # A protocol buffer option, which can be attached to a message, field,

6471

# enumeration, etc.

6472

"value": { # The option's value packed in an Any message. If the value is a primitive,

6473

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6474

# should be used. If the value is an enum, it should be stored as an int32

6475

# value using the google.protobuf.Int32Value type.

6476

"a_key": "", # Properties of the object. Contains field @type with type URL.

6477

},

6478

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6479

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6480

# For custom options, it should be the fully-qualified name. For example,

6481

# `"google.api.http"`.

6482

},

6483

],

6484

"fields": [ # The list of fields.

6485

{ # A single field of a message type.

6486

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6487

"name": "A String", # The field name.

6488

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6489

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6490

"number": 42, # The field number.

6491

"kind": "A String", # The field type.

6492

"jsonName": "A String", # The field JSON name.

6493

"options": [ # The protocol buffer options.

6494

{ # A protocol buffer option, which can be attached to a message, field,

6495

# enumeration, etc.

6496

"value": { # The option's value packed in an Any message. If the value is a primitive,

6497

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6498

# should be used. If the value is an enum, it should be stored as an int32

6499

# value using the google.protobuf.Int32Value type.

6500

"a_key": "", # Properties of the object. Contains field @type with type URL.

6501

},

6502

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6503

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6504

# For custom options, it should be the fully-qualified name. For example,

6505

# `"google.api.http"`.

6506

},

6507

],

6508

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6509

# types. The first type has index 1; zero means the type is not in the list.

6510

"packed": True or False, # Whether to use alternative packed wire representation.

6511

"cardinality": "A String", # The field cardinality.

6512

},

6513

],

6514

"name": "A String", # The fully qualified message name.

6515

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6516

"A String",

6517

],

6518

"syntax": "A String", # The source syntax.

6519

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6520

# protobuf element, like the file in which it is defined.

6521

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6522

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

6527

"sourceFiles": [ # All files used during config generation.

6528

{

6529

"a_key": "", # Properties of the object. Contains field @type with type URL.

6530

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6531

],

6532

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6533

"http": { # Defines the HTTP configuration for an API service. It contains a list of # HTTP configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6534

# HttpRule, each specifying the mapping of an RPC method

6535

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6536

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

6537

# cases of single segment matches in reserved expansion, where "%2F" will be

6538

# left encoded.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6539

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6540

# The default behavior is to not decode RFC 6570 reserved characters in multi

6541

# segment matches.

6542

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

6543

#

6544

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6545

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6546

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6547

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

6548

# more HTTP REST endpoints. It allows developers to build a single API service

6549

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

6550

# APIs](https://github.com/googleapis/googleapis),

6551

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

6552

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

6553

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

6554

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6555

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6556

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

6557

# how different portions of the gRPC request message are mapped to the URL

6558

# path, URL query parameters, and HTTP request body. It also controls how the

6559

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

6560

# typically specified as an `google.api.http` annotation on the gRPC method.

6561

#

6562

# Each mapping specifies a URL path template and an HTTP method. The path

6563

# template may refer to one or more fields in the gRPC request message, as long

6564

# as each field is a non-repeated field with a primitive (non-message) type.

6565

# The path template controls how fields of the request message are mapped to

6566

# the URL path.

6567

#

6568

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6569

#

6570

# service Messaging {

6571

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6572

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6573

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6574

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6575

# }

6576

# }

6577

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6578

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6579

# }

6580

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6581

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6582

# }

6583

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6584

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6585

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6586

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6587

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6588

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6589

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6590

# Any fields in the request message which are not bound by the path template

6591

# automatically become HTTP query parameters if there is no HTTP request body.

6592

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6593

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6594

# service Messaging {

6595

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6596

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6597

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6598

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6599

# }

6600

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6601

# message GetMessageRequest {

6602

# message SubMessage {

6603

# string subfield = 1;

6604

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6605

# string message_id = 1; // Mapped to URL path.

6606

# int64 revision = 2; // Mapped to URL query parameter `revision`.

6607

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6608

# }

6609

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6610

# This enables a HTTP JSON to RPC mapping as below:

6611

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6612

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6613

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6614

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6615

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

6616

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6617

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6618

# Note that fields which are mapped to URL query parameters must have a

6619

# primitive type or a repeated primitive type or a non-repeated message type.

6620

# In the case of a repeated type, the parameter can be repeated in the URL

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6621

# as `...?param=A&param=B`. In the case of a message type, each field of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6622

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6623

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6624

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6625

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6626

# specifies the mapping. Consider a REST update method on the

6627

# message resource collection:

6628

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6629

# service Messaging {

6630

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

6631

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6632

# patch: "/v1/messages/{message_id}"

6633

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

6638

# string message_id = 1; // mapped to the URL

6639

# Message message = 2; // mapped to the body

6640

# }

6641

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6642

# The following HTTP JSON to RPC mapping is enabled, where the

6643

# representation of the JSON in the request body is determined by

6644

# protos JSON encoding:

6645

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6646

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6647

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6648

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6649

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6650

#

6651

# The special name `*` can be used in the body mapping to define that

6652

# every field not bound by the path template should be mapped to the

6653

# request body. This enables the following alternative definition of

6654

# the update method:

6655

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6656

# service Messaging {

6657

# rpc UpdateMessage(Message) returns (Message) {

6658

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6659

# patch: "/v1/messages/{message_id}"

6660

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

6666

# string text = 2;

6667

# }

6668

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6669

#

6670

# The following HTTP JSON to RPC mapping is enabled:

6671

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6672

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6673

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6674

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6675

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6676

#

6677

# Note that when using `*` in the body mapping, it is not possible to

6678

# have HTTP parameters, as all fields not bound by the path end in

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6679

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6680

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6681

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6682

#

6683

# It is possible to define multiple HTTP methods for one RPC by using

6684

# the `additional_bindings` option. Example:

6685

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6686

# service Messaging {

6687

# rpc GetMessage(GetMessageRequest) returns (Message) {

6688

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6689

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6690

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6691

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6692

# }

6693

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6694

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6695

# }

6696

# message GetMessageRequest {

6697

# string message_id = 1;

6698

# string user_id = 2;

6699

# }

6700

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6701

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6702

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6703

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6704

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6705

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

6706

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

6707

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6708

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6709

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6710

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6711

# 1. Leaf request fields (recursive expansion nested messages in the request

6712

# message) are classified into three categories:

6713

# - Fields referred by the path template. They are passed via the URL path.

6714

# - Fields referred by the HttpRule.body. They are passed via the HTTP

6715

# request body.

6716

# - All other fields are passed via the URL query parameters, and the

6717

# parameter name is the field path in the request message. A repeated

6718

# field can be represented as multiple query parameters under the same

6719

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6720

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6721

# are passed via URL path and HTTP request body.

6722

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

6723

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6724

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6725

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6726

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6727

# Template = "/" Segments [ Verb ] ;

6728

# Segments = Segment { "/" Segment } ;

6729

# Segment = "*" | "**" | LITERAL | Variable ;

6730

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

6731

# FieldPath = IDENT { "." IDENT } ;

6732

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6733

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6734

# The syntax `*` matches a single URL path segment. The syntax `**` matches

6735

# zero or more URL path segments, which must be the last part of the URL path

6736

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6737

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6738

# The syntax `Variable` matches part of the URL path as specified by its

6739

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6740

# matches a single path segment, its template may be omitted, e.g. `{var}`

6741

# is equivalent to `{var=*}`.

6742

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6743

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

6744

# contains any reserved character, such characters should be percent-encoded

6745

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6746

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6747

# If a variable contains exactly one path segment, such as `"{var}"` or

6748

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6749

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

6750

# server side does the reverse decoding. Such variables show up in the

6751

# [Discovery

6752

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6753

# `{var}`.

6754

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6755

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

6756

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6757

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6758

# The server side does the reverse decoding, except "%2F" and "%2f" are left

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6759

# unchanged. Such variables show up in the

6760

# [Discovery

6761

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6762

# `{+var}`.

6763

#

6764

# ## Using gRPC API Service Configuration

6765

#

6766

# gRPC API Service Configuration (service config) is a configuration language

6767

# for configuring a gRPC service to become a user-facing product. The

6768

# service config is simply the YAML representation of the `google.api.Service`

6769

# proto message.

6770

#

6771

# As an alternative to annotating your proto file, you can configure gRPC

6772

# transcoding in your service config YAML files. You do this by specifying a

6773

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

6774

# effect as the proto annotation. This can be particularly useful if you

6775

# have a proto that is reused in multiple services. Note that any transcoding

6776

# specified in the service config will override any matching transcoding

6777

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

6784

# - selector: example.v1.Messaging.GetMessage

6785

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

6790

# proto to JSON conversion must follow the [proto3

6791

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

6792

#

6793

# While the single segment variable follows the semantics of

6794

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

6795

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

6796

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

6797

# does not expand special characters like `?` and `#`, which would lead

6798

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

6799

# for multi segment variables.

6800

#

6801

# The path variables **must not** refer to any repeated or mapped field,

6802

# because client libraries are not capable of handling such variable expansion.

6803

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6804

# The path variables **must not** capture the leading "/" character. The reason

6805

# is that the most common use case "{var}" does not capture the leading "/"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6806

# character. For consistency, all path variables must share the same behavior.

6807

#

6808

# Repeated message fields must not be mapped to URL query parameters, because

6809

# no client library can support such complicated mapping.

6810

#

6811

# If an API needs to use a JSON array for request or response body, it can map

6812

# the request or response body to a repeated field. However, some gRPC

6813

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6814

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

6815

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6816

# not contain an `additional_bindings` field themselves (that is,

6817

# the nesting may only be one level deep).

6818

# Object with schema name: HttpRule

6819

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6820

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6821

# response body. When omitted, the entire response message will be used

6822

# as the HTTP response body.

6823

#

6824

# NOTE: The referred field must be present at the top-level of the response

6825

# message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6826

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

6827

# body, or `*` for mapping all request fields not captured by the path

6828

# pattern to the HTTP body, or omitted for not having any HTTP request body.

6829

#

6830

# NOTE: the referred field must be present at the top-level of the request

6831

# message type.

6832

"selector": "A String", # Selects a method to which this rule applies.

6833

#

6834

# Refer to selector for syntax details.

6835

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

6836

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

6837

# included in the `pattern` field, such as HEAD, or "*" to leave the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6838

# HTTP method unspecified for this rule. The wild-card rule is useful

6839

# for services that provide content to Web (HTML) clients.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6840

"kind": "A String", # The name of this custom HTTP verb.

6841

"path": "A String", # The path matched by this custom verb.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6842

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6843

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

6844

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

6845

# resources.

6846

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

6847

# half-duplex streaming method.

6848

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6849

},

6850

],

6851

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6852

"systemParameters": { # ### System parameter configuration # System parameter configuration.

6853

#

6854

# A system parameter is a special kind of parameter defined by the API

6855

# system, not by an individual API. It is typically mapped to an HTTP header

6856

# and/or a URL query parameter. This configuration specifies which methods

6857

# change the names of the system parameters.

6858

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6859

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6860

# The parameters defined here will override the default parameters

6861

# implemented by the system. If this field is missing from the service

6862

# config, default system parameters will be used. Default system parameters

6863

# and names is implementation-dependent.

6864

#

6865

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

6873

#

6874

#

6875

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

6880

# parameters:

6881

# - name: api_key

6882

# http_header: Api-Key1

6883

# - name: api_key

6884

# http_header: Api-Key2

6885

#

6886

# **NOTE:** All service configuration rules follow "last one wins" order.

6887

{ # Define a system parameter rule mapping system parameter definitions to

6888

# methods.

6889

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

6890

# For a given method call, only one of them should be used. If multiple

6891

# names are used the behavior is implementation-dependent.

6892

# If none of the specified names are present the behavior is

6893

# parameter-dependent.

6894

{ # Define a parameter's name and location. The parameter may be passed as either

6895

# an HTTP header or a URL query parameter, and if both are passed the behavior

6896

# is implementation-dependent.

6897

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

6898

# insensitive.

6899

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

6900

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

6901

# sensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6902

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6903

],

6904

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

6905

# methods in all APIs.

6906

#

6907

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

6912

"rules": [ # A list of API backend rules that apply to individual API methods.

6913

#

6914

# **NOTE:** All service configuration rules follow "last one wins" order.

6915

{ # A backend rule provides configuration for an individual API element.

6916

"protocol": "A String", # The protocol used for sending a request to the backend.

6917

# The supported values are "http/1.1" and "h2".

6918

#

6919

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

6929

# to "h2" for improved performance.

6930

#

6931

# Configuring this field to non-default values is only supported for secure

6932

# HTTP backends. This field will be ignored for all other backends.

6933

#

6934

# See

6935

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

6936

# for more details on the supported values.

6937

"selector": "A String", # Selects the methods to which this rule applies.

6938

#

6939

# Refer to selector for syntax details.

6940

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

6941

# operation. The default is no deadline.

6942

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

6943

# varies based on the request protocol and deployment environment.

6944

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

6945

# value lower than this will be rejected.

6946

"address": "A String", # The address of the API backend.

6947

#

6948

# The scheme is used to determine the backend protocol and security.

6949

# The following schemes are accepted:

6950

#

6951

# SCHEME PROTOCOL SECURITY

# http:// HTTP None

# https:// HTTP TLS

# grpc:// gRPC None

# grpcs:// gRPC TLS

#

# It is recommended to explicitly include a scheme. Leaving out the scheme

6958

# may cause constrasting behaviors across platforms.

6959

#

6960

# If the port is unspecified, the default is:

6961

# - 80 for schemes without TLS

6962

# - 443 for schemes with TLS

6963

#

6964

# For HTTP backends, use protocol

6965

# to specify the protocol version.

6966

"pathTranslation": "A String",

6967

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

6968

# This ID token will be added in the HTTP "authorization" header, and sent

6969

# to the backend.

6970

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

6971

# original "Authorization" HTTP header will be preserved. If the header is

6972

# used to carry the original token and is expected by the backend, this

6973

# field must be set to true to preserve the header.

6974

"renameTo": "A String", # Unimplemented. Do not use.

6975

#

6976

# The new name the selected proto elements should be renamed to.

6977

#

6978

# The package, the service and the method can all be renamed.

6979

# The backend server should implement the renamed proto. However, clients

6980

# should call the original method, and ESF routes the traffic to the renamed

6981

# method.

6982

#

6983

# HTTP clients should call the URL mapped to the original method.

6984

# gRPC and Stubby clients should call the original method with package name.

6985

#

6986

# For legacy reasons, ESF allows Stubby clients to call with the

6987

# short name (without the package name). However, for API Versioning(or

6988

# multiple methods mapped to the same short name), all Stubby clients must

6989

# call the method's full name with the package name, otherwise the first one

6990

# (selector) wins.

6991

#

6992

# If this `rename_to` is specified with a trailing `*`, the `selector` must

6993

# be specified with a trailing `*` as well. The all element short names

6994

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

7000

# rename_to: google.example.library.*

7001

#

7002

# The selector matches `google.example.library.v1.Library.CreateShelf` and

7003

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

7004

# `google.example.library.Library.CreateShelf` and

7005

# `google.example.library.Library.CreateBook`. It essentially renames the

7006

# proto package name section of the matched proto service and methods.

},

],

},

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

7011

#

7012

# Example:

7013

# <pre><code>documentation:

7014

# summary: >

7015

# The Google Calendar API gives access

7016

# to most calendar features.

7017

# pages:

7018

# - name: Overview

7019

# content: &#40;== include google/foo/overview.md ==&#41;

7020

# - name: Tutorial

7021

# content: &#40;== include google/foo/tutorial.md ==&#41;

7022

# subpages;

7023

# - name: Java

7024

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

7025

# rules:

7026

# - selector: google.calendar.Calendar.Get

7027

# description: >

7028

# ...

7029

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

7034

# standard markdown features, definition lists, tables and fenced

7035

# code blocks are supported. Section headers can be provided and are

7036

# interpreted relative to the section nesting of the context where

7037

# a documentation fragment is embedded.

7038

#

7039

# Documentation from the IDL is merged with documentation defined

7040

# via the config at normalization time, where documentation provided

7041

# by config rules overrides IDL provided.

7042

#

7043

# A number of constructs specific to the API platform are supported

7044

# in documentation text.

7045

#

7046

# In order to reference a proto element, the following

7047

# notation can be used:

7048

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

7049

# To override the display text used for the link, this can be used:

7050

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

7051

# Text can be excluded from doc using the following notation:

7052

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

7053

#

7054

# A few directives are available in documentation. Note that

7055

# directives must appear on a single line to be properly

7056

# identified. The `include` directive includes a markdown file from

7057

# an external source:

7058

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

7059

# The `resource_for` directive marks a message to be the resource of

7060

# a collection in REST view. If it is not specified, tools attempt

7061

# to infer the resource from the operations in a collection:

7062

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

7063

# The directive `suppress_warning` does not directly affect documentation

7064

# and is documented together with service config validation.

7065

"documentationRootUrl": "A String", # The URL to the root of documentation.

7066

"rules": [ # A list of documentation rules that apply to individual API elements.

7067

#

7068

# **NOTE:** All service configuration rules follow "last one wins" order.

7069

{ # A documentation rule provides information about individual API elements.

7070

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

7071

# an element is marked as `deprecated`.

7072

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

7073

# qualified name of the element which may end in "*", indicating a wildcard.

7074

# Wildcards are only allowed at the end and for a whole component of the

7075

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

7076

# wildcard will match one or more components. To specify a default for all

7077

# applicable elements, the whole pattern "*" is used.

7078

"description": "A String", # Description of the selected API(s).

7079

},

7080

],

7081

"summary": "A String", # A short summary of what the service does. Can only be provided by

7082

# plain text.

7083

"overview": "A String", # Declares a single overview page. For example:

7084

# <pre><code>documentation:

7085

# summary: ...

7086

# overview: &#40;== include overview.md ==&#41;

7087

# </code></pre>

7088

# This is a shortcut for the following declaration (using pages style):

7089

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

7094

# </code></pre>

7095

# Note: you cannot specify both `overview` field and `pages` field.

7096

"pages": [ # The top level pages for the documentation set.

7097

{ # Represents a documentation page. A page can contain subpages to represent

7098

# nested documentation set structure.

7099

"name": "A String", # The name of the page. It will be used as an identity of the page to

7100

# generate URI of the page, text of the link to this page in navigation,

7101

# etc. The full page name (start from the root page name to this page

7102

# concatenated with `.`) can be used as reference to the page in your

7103

# documentation. For example:

7104

# <pre><code>pages:

7105

# - name: Tutorial

7106

# content: &#40;== include tutorial.md ==&#41;

7107

# subpages:

7108

# - name: Java

7109

# content: &#40;== include tutorial_java.md ==&#41;

7110

# </code></pre>

7111

# You can reference `Java` page using Markdown reference link syntax:

7112

# `Java`.

7113

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

7114

# ==&#41;</code> to include content from a Markdown file.

7115

"subpages": [ # Subpages of this page. The order of subpages specified here will be

7116

# honored in the generated docset.

7117

# Object with schema name: Page

],

},

],

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

7122

# from the yaml file) is not suitable. This can be seen in any fully

7123

# specified service urls as well as sections that show a base that other

7124

# urls are relative to.

7125

},

7126

"logging": { # Logging configuration of the service. # Logging configuration.

7127

#

7128

# The following example shows how to configure logs to be sent to the

7129

# producer and consumer projects. In the example, the `activity_history`

7130

# log is sent to both the producer and consumer projects, whereas the

7131

# `purchase_history` log is only sent to the producer project.

7132

#

7133

# monitored_resources:

7134

# - type: library.googleapis.com/branch

7135

# labels:

7136

# - key: /city

7137

# description: The city where the library branch is located in.

7138

# - key: /name

7139

# description: The name of the branch.

7140

# logs:

7141

# - name: activity_history

7142

# labels:

7143

# - key: /customer_id

7144

# - name: purchase_history

7145

# logging:

7146

# producer_destinations:

7147

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

7152

# - monitored_resource: library.googleapis.com/branch

7153

# logs:

7154

# - activity_history

7155

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

7156

# There can be multiple producer destinations, each one must have a

7157

# different monitored resource type. A log can be used in at most

7158

# one producer destination.

7159

{ # Configuration of a specific logging destination (the producer project

7160

# or the consumer project).

7161

"logs": [ # Names of the logs to be sent to this destination. Each name must

7162

# be defined in the Service.logs section. If the log name is

7163

# not a domain scoped name, it will be automatically prefixed with

7164

# the service name followed by "/".

7165

"A String",

7166

],

7167

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

7168

# Service.monitored_resources section.

7169

},

7170

],

7171

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

7172

# There can be multiple consumer destinations, each one must have a

7173

# different monitored resource type. A log can be used in at most

7174

# one consumer destination.

7175

{ # Configuration of a specific logging destination (the producer project

7176

# or the consumer project).

7177

"logs": [ # Names of the logs to be sent to this destination. Each name must

7178

# be defined in the Service.logs section. If the log name is

7179

# not a domain scoped name, it will be automatically prefixed with

7180

# the service name followed by "/".

7181

"A String",

7182

],

7183

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

7184

# Service.monitored_resources section.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

7189

# by the Service.monitoring and Service.logging configurations.

7190

{ # An object that describes the schema of a MonitoredResource object using a

7191

# type name and a set of labels. For example, the monitored resource

7192

# descriptor for Google Compute Engine VM instances has a type of

7193

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

7194

# `"zone"` to identify particular VM instances.

7195

#

7196

# Different APIs can support different monitored resource types. APIs generally

7197

# provide a `list` method that returns the monitored resource descriptors used

7198

# by the API.

7199

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

7200

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

7201

# without any article or other determiners. For example,

7202

# `"Google Cloud SQL Database"`.

7203

"description": "A String", # Optional. A detailed description of the monitored resource type that might

7204

# be used in documentation.

7205

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

7206

"labels": [ # Required. A set of labels used to describe instances of this monitored

7207

# resource type. For example, an individual Google Cloud SQL database is

7208

# identified by values for the labels `"database_id"` and `"zone"`.

7209

{ # A description of a label.

7210

"key": "A String", # The label key.

7211

"description": "A String", # A human-readable description for the label.

7212

"valueType": "A String", # The type of data that can be assigned to the label.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7213

},

7214

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7215

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

7216

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

7217

# {type} is the value of the `type` field in this object and

7218

# {project_id} is a project ID that provides API-specific context for

7219

# accessing the type. APIs that do not use project information can use the

7220

# resource name format `"monitoredResourceDescriptors/{type}"`.

7221

"type": "A String", # Required. The monitored resource type. For example, the type

7222

# `"cloudsql_database"` represents databases in Google Cloud SQL.

7223

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7224

},

7225

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7226

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7227

#

7228

# Example:

7229

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

7235

# - google.rpc.context.OriginContext

7236

#

7237

# The above specifies that all methods in the API request

7238

# `google.rpc.context.ProjectContext` and

7239

# `google.rpc.context.OriginContext`.

7240

#

7241

# Available context types are defined in package

7242

# `google.rpc.context`.

7243

#

7244

# This also provides mechanism to whitelist any protobuf message extension that

7245

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

7246

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

7247

# specific protobuf types that can appear in grpc metadata as follows in your

# yaml file:

#

# Example:

#

# context:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

7255

# allowed_request_extensions:

7256

# - google.foo.v1.NewExtension

7257

# allowed_response_extensions:

7258

# - google.foo.v1.NewExtension

7259

#

7260

# You can also specify extension ID instead of fully qualified extension name

7261

# here.

7262

"rules": [ # A list of RPC context rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7263

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7264

# **NOTE:** All service configuration rules follow "last one wins" order.

7265

{ # A context rule provides information about the context for an individual API

7266

# element.

7267

"requested": [ # A list of full type names of requested contexts.

7268

"A String",

7269

],

7270

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7271

# side channel from client to backend.

7272

"A String",

7273

],

7274

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7275

# side channel from backend to client.

7276

"A String",

7277

],

7278

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7279

#

7280

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7281

"provided": [ # A list of full type names of provided contexts.

7282

"A String",

7283

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7284

},

7285

],

7286

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7287

"enums": [ # A list of all enum types included in this API service. Enums

7288

# referenced directly or indirectly by the `apis` are automatically

7289

# included. Enums which are not referenced but shall be included

7290

# should be listed here by name. Example:

7291

#

7292

# enums:

7293

# - name: google.someapi.v1.SomeEnum

7294

{ # Enum type definition.

7295

"name": "A String", # Enum type name.

7296

"enumvalue": [ # Enum value definitions.

7297

{ # Enum value definition.

7298

"name": "A String", # Enum value name.

7299

"options": [ # Protocol buffer options.

7300

{ # A protocol buffer option, which can be attached to a message, field,

7301

# enumeration, etc.

7302

"value": { # The option's value packed in an Any message. If the value is a primitive,

7303

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7304

# should be used. If the value is an enum, it should be stored as an int32

7305

# value using the google.protobuf.Int32Value type.

7306

"a_key": "", # Properties of the object. Contains field @type with type URL.

7307

},

7308

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7309

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7310

# For custom options, it should be the fully-qualified name. For example,

7311

# `"google.api.http"`.

7312

},

7313

],

7314

"number": 42, # Enum value number.

7315

},

7316

],

7317

"options": [ # Protocol buffer options.

7318

{ # A protocol buffer option, which can be attached to a message, field,

7319

# enumeration, etc.

7320

"value": { # The option's value packed in an Any message. If the value is a primitive,

7321

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7322

# should be used. If the value is an enum, it should be stored as an int32

7323

# value using the google.protobuf.Int32Value type.

7324

"a_key": "", # Properties of the object. Contains field @type with type URL.

7325

},

7326

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7327

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7328

# For custom options, it should be the fully-qualified name. For example,

7329

# `"google.api.http"`.

7330

},

7331

],

7332

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

7333

# protobuf element, like the file in which it is defined.

7334

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7335

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

7336

},

7337

"syntax": "A String", # The source syntax.

7338

},

7339

],

7340

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7341

# by the client for tracking purpose. Must be no longer than 63 characters

7342

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

7343

# empty, the server may choose to generate one instead.

7344

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

7345

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

7346

# service producer.

7347

#

7348

# Google Service Management currently only supports

7349

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

7350

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

7351

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

7352

# documented in https://cloud.google.com/pubsub/docs/overview.

7353

"rules": [ # A list of usage rules that apply to individual API methods.

7354

#

7355

# **NOTE:** All service configuration rules follow "last one wins" order.

7356

{ # Usage configuration rules for the service.

7357

#

7358

# NOTE: Under development.

7359

#

7360

#

7361

# Use this rule to configure unregistered calls for the service. Unregistered

7362

# calls are calls that do not contain consumer project identity.

7363

# (Example: calls that do not contain an API key).

7364

# By default, API methods do not allow unregistered calls, and each method call

7365

# must be identified by a consumer project identity. Use this rule to

7366

# allow/disallow unregistered calls.

7367

#

7368

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

7374

#

7375

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

7380

# allow_unregistered_calls: true

7381

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

7382

# methods in all APIs.

7383

#

7384

# Refer to selector for syntax details.

7385

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

7386

# plane features, such as quota and billing, will not be available.

7387

# This flag is used by Google Cloud Endpoints to bypass checks for internal

7388

# methods, such as service health check methods.

7389

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

7390

# that don't identify any user or application.

7391

},

7392

],

7393

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

7394

#

7395

#

7396

# Use this field to configure per-product per-project service identity.

7397

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

7402

# display_name: "Cloud XXX Service Agent"

7403

# description: "Used as the identity of Cloud XXX to access resources"

7404

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

7405

#

7406

# An example name would be:

7407

# `projects/123456789`

7408

"displayName": "A String", # Optional. A user-specified name for the service account.

7409

# Must be less than or equal to 100 UTF-8 bytes.

7410

"description": "A String", # Optional. A user-specified opaque description of the service account.

7411

# Must be less than or equal to 256 UTF-8 bytes.

7412

},

7413

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

7414

# service. Each requirement is of the form <service.name>/<requirement-id>;

7415

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7420

{ # Defines a metric type and its schema. Once a metric descriptor is created,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7421

# deleting or altering it stops data collection and makes the metric type's

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7422

# existing data unusable.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7423

"name": "A String", # The resource name of the metric descriptor.

7424

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7425

# URL-encoded. All user-defined metric types have the DNS name

7426

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

7427

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7428

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7429

# "custom.googleapis.com/invoice/paid/amount"

7430

# "external.googleapis.com/prometheus/up"

7431

# "appengine.googleapis.com/http/server/response_latencies"

7432

"metadata": { # Additional annotations that can be used to guide the usage of a metric. # Optional. Metadata which can be used to guide usage of the metric.

7433

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

7434

# age are guaranteed to be ingested and available to be read, excluding

7435

# data loss due to errors.

7436

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

7437

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

7438

# periodically, consecutive data points are stored at this time interval,

7439

# excluding data loss due to errors. Metrics with a higher granularity have

7440

# a smaller sampling period.

7441

},

7442

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

7443

# Some combinations of `metric_kind` and `value_type` might not be supported.

7444

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

7445

# Some combinations of `metric_kind` and `value_type` might not be supported.

7446

"description": "A String", # A detailed description of the metric, which can be used in documentation.

7447

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

7448

# Use sentence case without an ending period, for example "Request count".

7449

# This field is optional but it is recommended to be set for any metrics

7450

# associated with user-visible concepts, such as Quota.

7451

"unit": "A String", # The units in which the metric value is reported. It is only applicable

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7452

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

7453

# defines the representation of the stored metric values.

7454

#

7455

# Different systems may scale the values to be more easily displayed (so a

7456

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

7457

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

7458

# `KBy`, then the value of the metric is always in thousands of bytes, no

7459

# matter how it may be displayed..

7460

#

7461

# If you want a custom metric to record the exact number of CPU-seconds used

7462

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

7463

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

7464

# CPU-seconds, then the value is written as `12005`.

7465

#

7466

# Alternatively, if you want a custom metric to record data in a more

7467

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

7468

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

7469

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

7470

#

7471

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7472

# Measure](http://unitsofmeasure.org/ucum.html) standard:

7473

#

7474

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

7484

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

7492

# * `Y` yotta (10^24)

7493

#

7494

# * `m` milli (10^-3)

7495

# * `u` micro (10^-6)

7496

# * `n` nano (10^-9)

7497

# * `p` pico (10^-12)

7498

# * `f` femto (10^-15)

7499

# * `a` atto (10^-18)

7500

# * `z` zepto (10^-21)

7501

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7508

#

7509

# **Grammar**

7510

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7511

# The grammar also includes these connectors:

7512

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7513

# * `/` division or ratio (as an infix operator). For examples,

7514

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

7515

# have `/s` in a metric `unit`; rates should always be computed at

7516

# query time from the underlying cumulative or delta value).

7517

# * `.` multiplication or composition (as an infix operator). For

7518

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7519

#

7520

# The grammar for a unit is as follows:

7521

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7522

# Expression = Component { "." Component } { "/" Component } ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7523

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7524

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7525

# | Annotation

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7526

# | "1"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7527

# ;

7528

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7529

# Annotation = "{" NAME "}" ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7530

#

7531

# Notes:

7532

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7533

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

7534

# is used alone, then the unit is equivalent to `1`. For examples,

7535

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7536

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7537

# containing `{` or `}`.

7538

# * `1` represents a unitary [dimensionless

7539

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

7540

# as in `1/s`. It is typically used when none of the basic units are

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7541

# appropriate. For example, "new users per day" can be represented as

7542

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

7543

# users). Alternatively, "thousands of page views per day" would be

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7544

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7545

# value of `5.3` would mean "5300 page views per day").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7546

# * `%` represents dimensionless value of 1/100, and annotates values giving

7547

# a percentage (so the metric values are typically in the range of 0..100,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7548

# and a metric value `3` means "3 percent").

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7549

# * `10^2.%` indicates a metric contains a ratio, typically in the range

7550

# 0..1, that will be multiplied by 100 and displayed as a percentage

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7551

# (so a metric value `0.03` means "3 percent").

7552

"monitoredResourceTypes": [ # Read-only. If present, then a time

7553

# series, which is identified partially by

7554

# a metric type and a MonitoredResourceDescriptor, that is associated

7555

# with this metric type can only be associated with one of the monitored

7556

# resource types listed here.

7557

"A String",

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7558

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7559

"launchStage": "A String", # Optional. The launch stage of the metric definition.

7560

"labels": [ # The set of labels that can be used to describe a specific

7561

# instance of this metric type. For example, the

7562

# `appengine.googleapis.com/http/server/response_latencies` metric

7563

# type has a label for the HTTP response code, `response_code`, so

7564

# you can look at latencies for successful responses or just

7565

# for responses that failed.

7566

{ # A description of a label.

7567

"key": "A String", # The label key.

7568

"description": "A String", # A human-readable description for the label.

7569

"valueType": "A String", # The type of data that can be assigned to the label.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7570

},

7571

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7572

},

7573

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7574

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7575

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7576

# Example for an API targeted for external use:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7577

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7578

# name: calendar.googleapis.com

7579

# authentication:

7580

# providers:

7581

# - id: google_calendar_auth

7582

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

7583

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7584

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7585

# - selector: "*"

7586

# requirements:

7587

# provider_id: google_calendar_auth

7588

"rules": [ # A list of authentication rules that apply to individual API methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7589

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7590

# **NOTE:** All service configuration rules follow "last one wins" order.

7591

{ # Authentication rules for the service.

7592

#

7593

# By default, if a method has any authentication requirements, every request

7594

# must include a valid credential matching one of the requirements.

7595

# It's an error to include more than one kind of credential in a single

7596

# request.

7597

#

7598

# If a method doesn't have any auth requirements, request credentials will be

7599

# ignored.

7600

"requirements": [ # Requirements for additional authentication providers.

7601

{ # User-defined authentication requirements, including support for

7602

# [JSON Web Token

7603

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

7604

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

7609

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

7610

# implemented and accepted in all the runtime components.

7611

#

7612

# The list of JWT

7613

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

7614

# that are allowed to access. A JWT containing any of these audiences will

7615

# be accepted. When this setting is absent, only JWTs with audience

7616

# "https://Service_name/API_name"

7617

# will be accepted. For example, if no audiences are in the setting,

7618

# LibraryService API will only accept JWTs with the following audience

7619

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

7624

# bookstore_web.apps.googleusercontent.com

7625

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7626

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7627

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7628

#

7629

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7630

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

7631

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

7632

# there are scopes defined for "Read-only access to Google Calendar" and

7633

# "Access to Cloud Platform". Users can consent to a scope for an application,

7634

# giving it permission to access that data on their behalf.

7635

#

7636

# OAuth scope specifications should be fairly coarse grained; a user will need

7637

# to see and understand the text description of what your scope means.

7638

#

7639

# In most cases: use one or at most two OAuth scopes for an entire family of

7640

# products. If your product has multiple APIs, you should probably be sharing

7641

# the OAuth scope across all of those APIs.

7642

#

7643

# When you need finer grained OAuth consent screens: talk with your product

7644

# management about how developers will use them in practice.

7645

#

7646

# Please note that even though each of the canonical scopes is enough for a

7647

# request to be accepted and passed to the backend, a request can still fail

7648

# due to the backend requiring additional scopes or permissions.

7649

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

7650

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

7655

# https://www.googleapis.com/auth/calendar.read

},

},

],

"providers": [ # Defines a set of authentication providers that a service supports.

7660

{ # Configuration for an authentication provider, including support for

7661

# [JSON Web Token

7662

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

7663

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

7664

# [OpenID

7665

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

7666

# Optional if the key set document:

7667

# - can be retrieved from

7668

# [OpenID

7669

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

7670

# the issuer.

7671

# - can be inferred from the email domain of the issuer (e.g. a Google

7672

# service account).

7673

#

7674

# Example: https://www.googleapis.com/oauth2/v1/certs

7675

"audiences": "A String", # The list of JWT

7676

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

7677

# that are allowed to access. A JWT containing any of these audiences will

7678

# be accepted. When this setting is absent, JWTs with audiences:

7679

# - "https://[service.name]/[google.protobuf.Api.name]"

7680

# - "https://[service.name]/"

7681

# will be accepted.

7682

# For example, if no audiences are in the setting, LibraryService API will

7683

# accept JWTs with the following audiences:

7684

# -

7685

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

7686

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

7691

# bookstore_web.apps.googleusercontent.com

7692

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

7693

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

7694

"issuer": "A String", # Identifies the principal that issued the JWT. See

7695

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

7696

# Usually a URL or an email address.

7697

#

7698

# Example: https://securetoken.google.com

7699

# Example: 1234567-compute@developer.gserviceaccount.com

7700

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

7701

# `AuthRequirement.provider_id`.

7702

#

7703

# Example: "bookstore_auth".

7704

"jwtLocations": [ # Defines the locations to extract the JWT.

7705

#

7706

# JWT locations can be either from HTTP headers or URL query parameters.

7707

# The rule is that the first match wins. The checking order is: checking

7708

# all headers first, then URL query parameters.

7709

#

7710

# If not specified, default to use following 3 locations:

7711

# 1) Authorization: Bearer

7712

# 2) x-goog-iap-jwt-assertion

7713

# 3) access_token query parameter

7714

#

7715

# Default locations can be specified as followings:

7716

# jwt_locations:

7717

# - header: Authorization

7718

# value_prefix: "Bearer "

7719

# - header: x-goog-iap-jwt-assertion

7720

# - query: access_token

7721

{ # Specifies a location to extract JWT from an API request.

7722

"header": "A String", # Specifies HTTP header name to extract JWT token.

7723

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

7724

# Only applies to "in" header type. Must be empty for "in" query type.

7725

# If not empty, the header value has to match (case sensitive) this prefix.

7726

# If not matched, JWT will not be extracted. If matched, JWT will be

7727

# extracted after the prefix is removed.

7728

#

7729

# For example, for "Authorization: Bearer {JWT}",

7730

# value_prefix="Bearer " with a space at the end.

7731

"query": "A String", # Specifies URL query parameter name to extract JWT token.

7732

},

7733

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7734

},

7735

],

7736

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7737

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

7738

# service controller handles features like abuse, quota, billing, logging,

7739

# monitoring, etc.

7740

"environment": "A String", # The service control environment to use. If empty, no control plane

7741

# feature (like quota and billing) will be enabled.

7742

},

7743

"configVersion": 42, # The semantic version of the service configuration. The config version

7744

# affects the interpretation of the service configuration. For example,

7745

# certain features are enabled by default for certain config versions.

7746

#

7747

# The latest config version is `3`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7748

},

7749

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7750

"nextPageToken": "A String", # The token of the next page of results.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

7756

<pre>Retrieves the next page of results.

7757

7758

Args:

7759

previous_request: The request for the previous page. (required)

7760

previous_response: The response from the request for the previous page. (required)

7761

7762

Returns:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7763

A request object that you can call 'execute()' on to request the next

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7764

page. Returns None if there are no more items in the collection.

</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7769

<code class="details" id="submit">submit(serviceName, body=None, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7770

<pre>Creates a new service configuration (version) for a managed service based

7771

on

7772

user-supplied configuration source files (for example: OpenAPI

7773

Specification). This method stores the source configurations as well as the

7774

generated service configuration. To rollout the service configuration to

7775

other services,

7776

please call CreateServiceRollout.

7777

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7778

Only the 100 most recent configuration sources and ones referenced by

7779

existing service configurtions are kept for each service. The rest will be

7780

deleted eventually.

7781

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7782

Operation<response: SubmitConfigSourceResponse>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7783

7784

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7785

serviceName: string, Required. The name of the service. See the [overview](/service-management/overview)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7786

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7787

body: object, The request body.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7788

The object takes the form of:

7789

7790

{ # Request message for SubmitConfigSource method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7791

"configSource": { # Represents a source file which is used to generate the service configuration # Required. The source configuration for the service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7792

# defined by `google.api.Service`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7793

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7794

# by the client for tracking purpose. If empty, the server may choose to

7795

# generate one instead.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7796

"files": [ # Set of source configuration files that are used to generate a service

7797

# configuration (`google.api.Service`).

7798

{ # Generic specification of a source configuration file

7799

"filePath": "A String", # The file name of the configuration file (full or relative path).

7800

"fileType": "A String", # The type of configuration file this represents.

7801

"fileContents": "A String", # The bytes that constitute the file.

7802

},

7803

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7804

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7805

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7806

# `google.api.Service` configuration based on the `ConfigSource` provided,

7807

# but the generated config and the sources will NOT be persisted.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7808

}

7809

7810

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

7817

7818

{ # This resource represents a long-running operation that is the result of a

7819

# network API call.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7820

"metadata": { # Service-specific metadata associated with the operation. It typically

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7821

# contains progress information and common metadata such as create time.

7822

# Some services might not provide such metadata. Any method that returns a

7823

# long-running operation should document the metadata type, if any.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7824

"a_key": "", # Properties of the object. Contains field @type with type URL.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7825

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7826

"done": True or False, # If the value is `false`, it means the operation is still in progress.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7827

# If `true`, the operation is completed, and either `error` or `response` is

7828

# available.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7829

"response": { # The normal response of the operation in case of success. If the original

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7830

# method returns no data on success, such as `Delete`, the response is

7831

# `google.protobuf.Empty`. If the original method is standard

7832

# `Get`/`Create`/`Update`, the response should be the resource. For other

7833

# methods, the response should have the type `XxxResponse`, where `Xxx`

7834

# is the original method name. For example, if the original method name

7835

# is `TakeSnapshot()`, the inferred response type is

7836

# `TakeSnapshotResponse`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7837

"a_key": "", # Properties of the object. Contains field @type with type URL.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7838

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7839

"name": "A String", # The server-assigned name, which is only unique within the same service that

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7840

# originally returns it. If you use the default HTTP mapping, the

7841

# `name` should be a resource name ending with `operations/{unique_id}`.

Bu Sun Kim