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-27 12:20:54 -0700

[diff] [blame^]

133

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

134

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

135

# monitoring, etc.

136

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

137

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

Bu Sun Kim

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

[diff] [blame]

138

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

139

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

140

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

141

# automatically included. Messages which are not referenced but

142

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

143

# should be listed here by name. Example:

144

#

145

# types:

146

# - name: google.protobuf.Int32

Bu Sun Kim

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

[diff] [blame]

147

{ # A protocol buffer message type.

Bu Sun Kim

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

[diff] [blame]

148

"fields": [ # The list of fields.

149

{ # A single field of a message type.

Bu Sun Kim

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

[diff] [blame]

150

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

151

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

Bu Sun Kim

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

[diff] [blame]

152

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

153

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

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

154

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

Bu Sun Kim

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

[diff] [blame]

155

"options": [ # The protocol buffer options.

156

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

157

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

158

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

159

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

160

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

161

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

162

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

163

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

164

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

165

# value using the google.protobuf.Int32Value type.

166

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

167

},

Bu Sun Kim

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

[diff] [blame]

168

},

169

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

170

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

171

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

Bu Sun Kim

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

[diff] [blame]

172

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

173

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

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

174

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

175

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

Bu Sun Kim

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

[diff] [blame]

176

},

177

],

Bu Sun Kim

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

[diff] [blame]

178

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

179

"A String",

180

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

181

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

182

"options": [ # The protocol buffer options.

183

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

184

# enumeration, etc.

185

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

186

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

187

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

188

# `"google.api.http"`.

189

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

190

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

191

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

192

# value using the google.protobuf.Int32Value type.

193

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

194

},

195

},

196

],

Bu Sun Kim

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

[diff] [blame]

197

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

198

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

199

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

200

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

201

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

202

},

203

},

204

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

205

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

206

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

207

{

208

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

Bu Sun Kim

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

[diff] [blame]

},

],

},

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

213

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

214

# typically goes through DNS verification to make sure the owner

215

# of the service also owns the DNS name.

Bu Sun Kim

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

[diff] [blame]

216

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

Bu Sun Kim

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

[diff] [blame]

217

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

218

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

Jon Wayne Parrott

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

[diff] [blame]

219

#

Bu Sun Kim

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

[diff] [blame]

220

# - name: library.googleapis.com/activity_history

221

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

222

# display_name: Activity

223

# labels:

224

# - key: /customer_id

225

# description: Identifier of a library customer

226

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

227

# Runtime requests that contain labels not specified here are

228

# considered invalid.

229

{ # A description of a label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

230

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

Bu Sun Kim

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

[diff] [blame]

231

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

232

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

Bu Sun Kim

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

[diff] [blame]

233

},

234

],

Bu Sun Kim

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

[diff] [blame]

235

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

236

# the documentation and can contain details.

237

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

238

# the user interface and should be concise.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

239

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

240

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

241

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

242

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

Bu Sun Kim

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

[diff] [blame]

243

},

244

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

245

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

246

{ # Defines a metric type and its schema. Once a metric descriptor is created,

247

# deleting or altering it stops data collection and makes the metric type's

248

# existing data unusable.

249

"type": "A String", # The metric type, including its DNS name prefix. The type is not

250

# URL-encoded. All user-defined metric types have the DNS name

251

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

252

# use a natural hierarchical grouping. For example:

253

#

254

# "custom.googleapis.com/invoice/paid/amount"

255

# "external.googleapis.com/prometheus/up"

256

# "appengine.googleapis.com/http/server/response_latencies"

257

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

258

# instance of this metric type. For example, the

259

# `appengine.googleapis.com/http/server/response_latencies` metric

260

# type has a label for the HTTP response code, `response_code`, so

261

# you can look at latencies for successful responses or just

262

# for responses that failed.

263

{ # A description of a label.

264

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

265

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

266

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

267

},

268

],

269

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

270

"monitoredResourceTypes": [ # Read-only. If present, then a time

271

# series, which is identified partially by

272

# a metric type and a MonitoredResourceDescriptor, that is associated

273

# with this metric type can only be associated with one of the monitored

274

# resource types listed here.

275

"A String",

276

],

277

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

278

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

279

# This field is optional but it is recommended to be set for any metrics

280

# associated with user-visible concepts, such as Quota.

281

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

282

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

283

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

284

# age are guaranteed to be ingested and available to be read, excluding

285

# data loss due to errors.

286

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

287

# periodically, consecutive data points are stored at this time interval,

288

# excluding data loss due to errors. Metrics with a higher granularity have

289

# a smaller sampling period.

290

},

291

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

292

# Some combinations of `metric_kind` and `value_type` might not be supported.

293

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

294

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

295

# defines the representation of the stored metric values.

296

#

297

# Different systems may scale the values to be more easily displayed (so a

298

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

299

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

300

# `KBy`, then the value of the metric is always in thousands of bytes, no

301

# matter how it may be displayed..

302

#

303

# If you want a custom metric to record the exact number of CPU-seconds used

304

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

305

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

306

# CPU-seconds, then the value is written as `12005`.

307

#

308

# Alternatively, if you want a custom metric to record data in a more

309

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

310

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

311

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

312

#

313

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

314

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

315

#

316

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

334

# * `Y` yotta (10^24)

335

#

336

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

337

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

338

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

339

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

340

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

341

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

342

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

343

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

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

#

# **Grammar**

#

# The grammar also includes these connectors:

354

#

355

# * `/` division or ratio (as an infix operator). For examples,

356

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

357

# have `/s` in a metric `unit`; rates should always be computed at

358

# query time from the underlying cumulative or delta value).

359

# * `.` multiplication or composition (as an infix operator). For

360

# examples, `GBy.d` or `k{watt}.h`.

361

#

362

# The grammar for a unit is as follows:

363

#

364

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

365

#

366

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

376

# is used alone, then the unit is equivalent to `1`. For examples,

377

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

378

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

379

# containing `{` or `}`.

380

# * `1` represents a unitary [dimensionless

381

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

382

# as in `1/s`. It is typically used when none of the basic units are

383

# appropriate. For example, "new users per day" can be represented as

384

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

385

# users). Alternatively, "thousands of page views per day" would be

386

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

387

# value of `5.3` would mean "5300 page views per day").

388

# * `%` represents dimensionless value of 1/100, and annotates values giving

389

# a percentage (so the metric values are typically in the range of 0..100,

390

# and a metric value `3` means "3 percent").

391

# * `10^2.%` indicates a metric contains a ratio, typically in the range

392

# 0..1, that will be multiplied by 100 and displayed as a percentage

393

# (so a metric value `0.03` means "3 percent").

394

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

395

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

396

# Some combinations of `metric_kind` and `value_type` might not be supported.

397

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

398

},

399

],

400

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

401

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

402

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

403

# should be listed here by name. Example:

404

#

405

# enums:

406

# - name: google.someapi.v1.SomeEnum

407

{ # Enum type definition.

408

"options": [ # Protocol buffer options.

409

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

410

# enumeration, etc.

411

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

412

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

413

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

414

# `"google.api.http"`.

415

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

416

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

417

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

418

# value using the google.protobuf.Int32Value type.

419

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

},

},

],

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

424

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

425

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

426

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

427

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

428

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

429

},

430

"enumvalue": [ # Enum value definitions.

431

{ # Enum value definition.

432

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

433

"number": 42, # Enum value number.

434

"options": [ # Protocol buffer options.

435

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

436

# enumeration, etc.

437

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

438

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

439

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

440

# `"google.api.http"`.

441

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

442

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

443

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

444

# value using the google.protobuf.Int32Value type.

445

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

},

},

],

},

],

},

],

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

454

#

455

# Example for an API targeted for external use:

456

#

457

# name: calendar.googleapis.com

458

# authentication:

459

# providers:

460

# - id: google_calendar_auth

461

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

462

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

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

467

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

468

#

469

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

470

{ # Authentication rules for the service.

471

#

472

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

473

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

474

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

475

# request.

476

#

477

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

478

# ignored.

479

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

480

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

481

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

482

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

483

#

484

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

485

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

486

#

487

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

488

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

489

# the OAuth scope across all of those APIs.

490

#

491

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

492

# management about how developers will use them in practice.

493

#

494

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

495

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

496

# due to the backend requiring additional scopes or permissions.

497

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

498

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

#

# Example:

#

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

503

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

504

},

505

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

506

{ # User-defined authentication requirements, including support for

507

# [JSON Web Token

508

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

509

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

510

# implemented and accepted in all the runtime components.

511

#

512

# The list of JWT

513

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

514

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

515

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

516

# "https://Service_name/API_name"

517

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

518

# LibraryService API will only accept JWTs with the following audience

519

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

524

# bookstore_web.apps.googleusercontent.com

525

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

#

# Example:

#

# provider_id: bookstore_auth

530

},

531

],

532

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

533

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

534

#

535

# Refer to selector for syntax details.

536

},

537

],

538

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

539

{ # Configuration for an authentication provider, including support for

540

# [JSON Web Token

541

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

542

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

543

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

544

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

545

# be accepted. When this setting is absent, JWTs with audiences:

546

# - "https://[service.name]/[google.protobuf.Api.name]"

547

# - "https://[service.name]/"

548

# will be accepted.

549

# For example, if no audiences are in the setting, LibraryService API will

550

# accept JWTs with the following audiences:

551

# -

552

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

553

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

558

# bookstore_web.apps.googleusercontent.com

559

"jwtLocations": [ # Defines the locations to extract the JWT.

560

#

561

# JWT locations can be either from HTTP headers or URL query parameters.

562

# The rule is that the first match wins. The checking order is: checking

563

# all headers first, then URL query parameters.

564

#

565

# If not specified, default to use following 3 locations:

566

# 1) Authorization: Bearer

567

# 2) x-goog-iap-jwt-assertion

568

# 3) access_token query parameter

569

#

570

# Default locations can be specified as followings:

571

# jwt_locations:

572

# - header: Authorization

573

# value_prefix: "Bearer "

574

# - header: x-goog-iap-jwt-assertion

575

# - query: access_token

576

{ # Specifies a location to extract JWT from an API request.

577

"query": "A String", # Specifies URL query parameter name to extract JWT token.

578

"header": "A String", # Specifies HTTP header name to extract JWT token.

579

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

580

# Only applies to "in" header type. Must be empty for "in" query type.

581

# If not empty, the header value has to match (case sensitive) this prefix.

582

# If not matched, JWT will not be extracted. If matched, JWT will be

583

# extracted after the prefix is removed.

584

#

585

# For example, for "Authorization: Bearer {JWT}",

586

# value_prefix="Bearer " with a space at the end.

587

},

588

],

589

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

590

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

591

# Usually a URL or an email address.

592

#

593

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

594

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

595

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

596

# `AuthRequirement.provider_id`.

597

#

598

# Example: "bookstore_auth".

599

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

600

# [OpenID

601

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

602

# Optional if the key set document:

603

# - can be retrieved from

604

# [OpenID

605

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

606

# the issuer.

607

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

608

# service account).

609

#

610

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

611

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

612

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

},

],

},

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

617

#

618

# Example:

619

# <pre><code>documentation:

620

# summary: >

621

# The Google Calendar API gives access

622

# to most calendar features.

623

# pages:

624

# - name: Overview

625

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

626

# - name: Tutorial

627

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

628

# subpages;

629

# - name: Java

630

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

631

# rules:

632

# - selector: google.calendar.Calendar.Get

633

# description: >

634

# ...

635

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

640

# standard markdown features, definition lists, tables and fenced

641

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

642

# interpreted relative to the section nesting of the context where

643

# a documentation fragment is embedded.

644

#

645

# Documentation from the IDL is merged with documentation defined

646

# via the config at normalization time, where documentation provided

647

# by config rules overrides IDL provided.

648

#

649

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

650

# in documentation text.

651

#

652

# In order to reference a proto element, the following

653

# notation can be used:

654

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

655

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

656

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

657

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

658

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

659

#

660

# A few directives are available in documentation. Note that

661

# directives must appear on a single line to be properly

662

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

663

# an external source:

664

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

665

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

666

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

667

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

668

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

669

# The directive `suppress_warning` does not directly affect documentation

670

# and is documented together with service config validation.

671

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

672

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

673

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

674

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

675

# urls are relative to.

676

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

677

#

678

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

679

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

680

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

681

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

682

# an element is marked as `deprecated`.

683

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

684

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

685

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

686

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

687

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

688

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

689

},

690

],

691

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

692

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

693

# nested documentation set structure.

694

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

695

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

696

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

697

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

698

# documentation. For example:

699

# <pre><code>pages:

700

# - name: Tutorial

701

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

702

# subpages:

703

# - name: Java

704

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

705

# </code></pre>

706

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

707

# `Java`.

708

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

709

# honored in the generated docset.

710

# Object with schema name: Page

711

],

712

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

713

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

714

},

715

],

716

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

717

# plain text.

718

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

719

# <pre><code>documentation:

720

# summary: ...

721

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

722

# </code></pre>

723

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

724

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

729

# </code></pre>

730

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

731

},

Bu Sun Kim

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

[diff] [blame]

732

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

733

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

734

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

735

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

736

# which cannot be resolved against the associated IDL files.

737

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

738

#

739

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

740

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

741

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

742

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

743

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

744

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

745

# detailed terminology.

746

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

747

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

748

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

749

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

750

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

751

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

752

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

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

},

Bu Sun Kim

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

[diff] [blame]

759

},

760

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

761

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

Bu Sun Kim

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

[diff] [blame]

762

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

763

# message.

764

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

765

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

766

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

767

},

Bu Sun Kim

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

[diff] [blame]

768

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

769

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

770

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

771

# documentation and options are inherited as follows:

772

#

773

# - If after comment and whitespace stripping, the documentation

774

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

775

# from the original method.

776

#

777

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

778

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

779

# inherited.

780

#

781

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

782

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

783

# version of the including interface plus the root path if

784

# specified.

785

#

786

# Example of a simple mixin:

787

#

788

# package google.acl.v1;

789

# service AccessControl {

790

# // Get the underlying ACL object.

791

# rpc GetAcl(GetAclRequest) returns (Acl) {

792

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

# }

# }

#

# package google.storage.v2;

797

# service Storage {

798

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

799

#

800

# // Get a data record.

801

# rpc GetData(GetDataRequest) returns (Data) {

802

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

# }

# }

#

# Example of a mixin configuration:

807

#

808

# apis:

809

# - name: google.storage.v2.Storage

810

# mixins:

811

# - name: google.acl.v1.AccessControl

812

#

813

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

814

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

815

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

816

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

817

# documentation and annotations as follows:

818

#

819

# service Storage {

820

# // Get the underlying ACL object.

821

# rpc GetAcl(GetAclRequest) returns (Acl) {

822

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

# }

# ...

# }

#

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

828

#

829

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

830

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

831

#

832

# apis:

833

# - name: google.storage.v2.Storage

834

# mixins:

835

# - name: google.acl.v1.AccessControl

836

# root: acls

837

#

838

# This implies the following inherited HTTP annotation:

839

#

840

# service Storage {

841

# // Get the underlying ACL object.

842

# rpc GetAcl(GetAclRequest) returns (Acl) {

843

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

# }

# ...

# }

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

848

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

849

# are rooted.

850

},

851

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

852

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

853

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

854

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

855

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

856

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

857

# consistent with what is provided here.

858

#

859

# The versioning schema uses [semantic

860

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

861

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

862

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

863

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

864

# chosen based on the product plan.

865

#

866

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

867

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

868

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

869

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

870

# experimental, non-GA interfaces.

871

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

872

{ # Method represents a method of an API interface.

873

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

874

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

875

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

876

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

877

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

Bu Sun Kim

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

[diff] [blame]

878

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

879

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

880

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

881

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

882

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

883

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

884

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

885

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

886

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

887

# value using the google.protobuf.Int32Value type.

888

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

889

},

Bu Sun Kim

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

[diff] [blame]

890

},

891

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

892

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

893

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

Bu Sun Kim

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

[diff] [blame]

894

},

895

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

896

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

897

# followed by the interface's simple name.

Bu Sun Kim

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

[diff] [blame]

898

},

899

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

900

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

901

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

909

# - google.foo.v1.AnotherError

910

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

911

"A String",

912

],

913

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

914

#

915

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

916

{ # A custom error rule.

917

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

918

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

919

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

920

#

921

# Refer to selector for syntax details.

Bu Sun Kim

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

[diff] [blame]

922

},

Jon Wayne Parrott

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

[diff] [blame]

923

],

924

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

925

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

926

# by the client for tracking purpose. Must be no longer than 63 characters

927

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

928

# empty, the server may choose to generate one instead.

929

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

930

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

931

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

932

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

933

"A String",

934

],

935

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

936

#

937

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

938

{ # Usage configuration rules for the service.

939

#

940

# NOTE: Under development.

941

#

942

#

943

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

944

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

945

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

946

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

947

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

948

# allow/disallow unregistered calls.

949

#

950

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

956

#

957

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

#

# usage:

# rules:

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

962

# allow_unregistered_calls: true

963

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

964

# methods in all APIs.

965

#

966

# Refer to selector for syntax details.

967

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

968

# that don't identify any user or application.

969

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

970

# plane features, such as quota and billing, will not be available.

971

# This flag is used by Google Cloud Endpoints to bypass checks for internal

972

# methods, such as service health check methods.

973

},

974

],

975

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

976

# service producer.

977

#

978

# Google Service Management currently only supports

979

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

980

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

981

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

982

# documented in https://cloud.google.com/pubsub/docs/overview.

983

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

984

#

985

#

986

# Use this field to configure per-product per-project service identity.

987

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

992

# display_name: "Cloud XXX Service Agent"

993

# description: "Used as the identity of Cloud XXX to access resources"

994

"displayName": "A String", # Optional. A user-specified name for the service account.

995

# Must be less than or equal to 100 UTF-8 bytes.

996

"description": "A String", # Optional. A user-specified opaque description of the service account.

997

# Must be less than or equal to 256 UTF-8 bytes.

998

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

999

#

1000

# An example name would be:

1001

# `projects/123456789`

1002

},

1003

},

1004

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

1005

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

1006

# defined APIs.

1007

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

1008

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

1009

# same service configuration, such as quota configuration and monitoring

1010

# configuration.

1011

#

1012

# Example service configuration:

1013

#

1014

# name: library-example.googleapis.com

1015

# endpoints:

1016

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

1017

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

1018

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

1019

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

1020

# # allowed to proceed.

1021

# - name: library-example.googleapis.com

1022

# allow_cors: true

1023

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

1024

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

1025

# handle requests to this [API

1026

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

1027

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

1028

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

1029

"allowCors": True or False, # Allowing

1030

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

1031

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

1032

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

1033

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

1034

# allowed to proceed.

1035

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

1036

"A String",

1037

],

1038

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

1039

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

1040

# aliases.

1041

#

1042

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

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

1048

# affects the interpretation of the service configuration. For example,

1049

# certain features are enabled by default for certain config versions.

1050

#

1051

# The latest config version is `3`.

Bu Sun Kim

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

[diff] [blame]

1052

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

1053

# HttpRule, each specifying the mapping of an RPC method

1054

# to one or more HTTP REST API methods.

Bu Sun Kim

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

[diff] [blame]

1055

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

1056

#

1057

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

Bu Sun Kim

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

[diff] [blame]

1058

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

1059

#

Bu Sun Kim

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

[diff] [blame]

1060

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

1061

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

1062

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

1063

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

1064

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

1065

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

1066

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

1067

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

1068

#

Bu Sun Kim

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

[diff] [blame]

1069

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

1070

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

1071

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

1072

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

1073

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

1074

#

1075

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

1076

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

1077

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

1078

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

1079

# the URL path.

1080

#

1081

# Example:

Jon Wayne Parrott

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

[diff] [blame]

1082

#

1083

# service Messaging {

1084

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

1085

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

1086

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

Bu Sun Kim

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

[diff] [blame]

1087

# };

Jon Wayne Parrott

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

[diff] [blame]

1088

# }

1089

# }

1090

# message GetMessageRequest {

Bu Sun Kim

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

[diff] [blame]

1091

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

Jon Wayne Parrott

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

[diff] [blame]

1092

# }

1093

# message Message {

Bu Sun Kim

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

[diff] [blame]

1094

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

Jon Wayne Parrott

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

[diff] [blame]

1095

# }

1096

#

Bu Sun Kim

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

[diff] [blame]

1097

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

Jon Wayne Parrott

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

[diff] [blame]

1098

#

Bu Sun Kim

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

[diff] [blame]

1099

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

1100

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

Bu Sun Kim

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

[diff] [blame]

1101

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

Jon Wayne Parrott

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

[diff] [blame]

1102

#

Bu Sun Kim

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

[diff] [blame]

1103

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

1104

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

1105

# For example:

Jon Wayne Parrott

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

[diff] [blame]

1106

#

Sai Cheemalapati

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

[diff] [blame]

1107

# service Messaging {

1108

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

1109

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

1110

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

Bu Sun Kim

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

[diff] [blame]

1111

# };

Sai Cheemalapati

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

[diff] [blame]

1112

# }

1113

# }

Jon Wayne Parrott

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

[diff] [blame]

1114

# message GetMessageRequest {

1115

# message SubMessage {

1116

# string subfield = 1;

1117

# }

Bu Sun Kim

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

[diff] [blame]

1118

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

1119

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

1120

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

Jon Wayne Parrott

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

[diff] [blame]

1121

# }

1122

#

Jon Wayne Parrott

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

[diff] [blame]

1123

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

1124

#

Bu Sun Kim

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

[diff] [blame]

1125

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

1126

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

Dan O'Meara

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

[diff] [blame]

1127

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

Bu Sun Kim

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

[diff] [blame]

1128

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

1129

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

1130

#

Bu Sun Kim

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

[diff] [blame]

1131

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

1132

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

1133

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

1134

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

1135

# message is mapped to a separate parameter, such as

Dan O'Meara

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

[diff] [blame]

1136

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

Jon Wayne Parrott

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

[diff] [blame]

1137

#

Bu Sun Kim

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

[diff] [blame]

1138

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

Jon Wayne Parrott

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

[diff] [blame]

1139

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

1140

# message resource collection:

1141

#

Jon Wayne Parrott

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

[diff] [blame]

1142

# service Messaging {

1143

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

1144

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

1145

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

1146

# body: "message"

Jon Wayne Parrott

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

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

1151

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

1152

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

1153

# }

1154

#

Jon Wayne Parrott

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

[diff] [blame]

1155

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

1156

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

1157

# protos JSON encoding:

1158

#

Bu Sun Kim

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

[diff] [blame]

1159

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

1160

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

Bu Sun Kim

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

[diff] [blame]

1161

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

1162

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

Jon Wayne Parrott

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

[diff] [blame]

1163

#

1164

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

1165

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

1166

# request body. This enables the following alternative definition of

1167

# the update method:

1168

#

Jon Wayne Parrott

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

[diff] [blame]

1169

# service Messaging {

1170

# rpc UpdateMessage(Message) returns (Message) {

1171

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

1172

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

1173

# body: "*"

Jon Wayne Parrott

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

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

1179

# string text = 2;

1180

# }

1181

#

Jon Wayne Parrott

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

[diff] [blame]

1182

#

1183

# The following HTTP JSON to RPC mapping is enabled:

1184

#

Bu Sun Kim

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

[diff] [blame]

1185

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

1186

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

Bu Sun Kim

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

[diff] [blame]

1187

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

1188

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

Jon Wayne Parrott

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

[diff] [blame]

1189

#

1190

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

1191

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

1192

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

Jon Wayne Parrott

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

[diff] [blame]

1193

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

Bu Sun Kim

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

[diff] [blame]

1194

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

Jon Wayne Parrott

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

[diff] [blame]

1195

#

1196

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

1197

# the `additional_bindings` option. Example:

1198

#

Jon Wayne Parrott

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

[diff] [blame]

1199

# service Messaging {

1200

# rpc GetMessage(GetMessageRequest) returns (Message) {

1201

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

1202

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

Jon Wayne Parrott

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

[diff] [blame]

1203

# additional_bindings {

Bu Sun Kim

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

[diff] [blame]

1204

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

Jon Wayne Parrott

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

[diff] [blame]

1205

# }

1206

# };

Jon Wayne Parrott

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

[diff] [blame]

1207

# }

Jon Wayne Parrott

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

[diff] [blame]

1208

# }

1209

# message GetMessageRequest {

1210

# string message_id = 1;

1211

# string user_id = 2;

1212

# }

1213

#

Bu Sun Kim

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

[diff] [blame]

1214

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

Jon Wayne Parrott

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

[diff] [blame]

1215

#

Bu Sun Kim

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

[diff] [blame]

1216

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

1217

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

Bu Sun Kim

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

[diff] [blame]

1218

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

1219

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

1220

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

1221

#

Bu Sun Kim

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

[diff] [blame]

1222

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

1223

#

Bu Sun Kim

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

[diff] [blame]

1224

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

1225

# message) are classified into three categories:

1226

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

1227

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

1228

# request body.

1229

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

1230

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

1231

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

1232

# name.

Bu Sun Kim

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

[diff] [blame]

1233

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

1234

# are passed via URL path and HTTP request body.

1235

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

1236

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

Jon Wayne Parrott

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

[diff] [blame]

1237

#

Bu Sun Kim

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

[diff] [blame]

1238

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

1239

#

Bu Sun Kim

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

[diff] [blame]

1240

# Template = "/" Segments [ Verb ] ;

1241

# Segments = Segment { "/" Segment } ;

1242

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

1243

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

1244

# FieldPath = IDENT { "." IDENT } ;

1245

# Verb = ":" LITERAL ;

Jon Wayne Parrott

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

[diff] [blame]

1246

#

Bu Sun Kim

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

[diff] [blame]

1247

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

1248

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

1249

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

1250

#

Bu Sun Kim

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

[diff] [blame]

1251

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

1252

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

Jon Wayne Parrott

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

[diff] [blame]

1253

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

1254

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

1255

#

Bu Sun Kim

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

[diff] [blame]

1256

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

1257

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

1258

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

1259

#

Bu Sun Kim

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

[diff] [blame]

1260

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

1261

# `"{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]

1262

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

1263

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

1264

# [Discovery

1265

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

1266

# `{var}`.

1267

#

Bu Sun Kim

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

[diff] [blame]

1268

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

1269

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

1270

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

Bu Sun Kim

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

[diff] [blame]

1271

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

1272

# unchanged. Such variables show up in the

1273

# [Discovery

1274

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

1275

# `{+var}`.

1276

#

1277

# ## Using gRPC API Service Configuration

1278

#

1279

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

1280

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

1281

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

1282

# proto message.

1283

#

1284

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

1285

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

1286

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

1287

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

1288

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

1289

# specified in the service config will override any matching transcoding

1290

# configuration in the proto.

#

# Example:

#

# http:

# rules:

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

1297

# - selector: example.v1.Messaging.GetMessage

1298

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

#

# ## Special notes

#

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

1303

# proto to JSON conversion must follow the [proto3

1304

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

1305

#

1306

# While the single segment variable follows the semantics of

1307

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

1308

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

1309

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

1310

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

1311

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

1312

# for multi segment variables.

1313

#

1314

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

1315

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

1316

#

Bu Sun Kim

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

[diff] [blame]

1317

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

1318

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

1319

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

1320

#

1321

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

1322

# no client library can support such complicated mapping.

1323

#

1324

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

1325

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

1326

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1327

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

1328

#

1329

# Refer to selector for syntax details.

1330

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

1331

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

1332

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

1333

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

1334

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

1335

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

1336

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

1337

},

Bu Sun Kim

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

[diff] [blame]

1338

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

1339

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

1340

# as the HTTP response body.

1341

#

1342

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

1343

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1344

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

1345

# half-duplex streaming method.

1346

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

1347

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

1348

# the nesting may only be one level deep).

1349

# Object with schema name: HttpRule

1350

],

1351

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

1352

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

1353

# resources.

1354

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

Bu Sun Kim

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

[diff] [blame]

1355

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

1356

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

1357

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

1358

#

1359

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

1360

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1361

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

1362

},

1363

],

1364

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

1365

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

1366

# left encoded.

1367

#

1368

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

1369

# segment matches.

1370

},

1371

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

1372

#

1373

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

1374

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

1375

# the monitored resources need at least one label key

1376

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

1377

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

1378

# recommended so they can be evolved independently:

1379

#

1380

#

1381

# monitored_resources:

1382

# - type: library.googleapis.com/billing_branch

1383

# labels:

1384

# - key: cloud.googleapis.com/location

1385

# description: |

1386

# Predefined label to support billing location restriction.

1387

# - key: city

1388

# description: |

1389

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

1390

# in.

1391

# - key: name

1392

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

1393

# metrics:

1394

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

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

1400

# - monitored_resource: library.googleapis.com/billing_branch

1401

# metrics:

1402

# - library.googleapis.com/book/borrowed_count

1403

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

1404

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

1405

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

1406

# one consumer destination.

1407

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

1408

# bill against consumer project).

1409

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

1410

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

1411

"A String",

1412

],

1413

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

1414

# Service.monitored_resources section.

},

],

},

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

1419

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

1420

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

1421

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

1422

# to define system APIs in ESF.

1423

{ # A protocol buffer message type.

1424

"fields": [ # The list of fields.

1425

{ # A single field of a message type.

1426

"number": 42, # The field number.

1427

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

1428

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

1429

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

1430

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

1431

"options": [ # The protocol buffer options.

1432

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

1433

# enumeration, etc.

1434

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

1435

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

1436

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

1437

# `"google.api.http"`.

1438

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

1439

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

1440

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

1441

# value using the google.protobuf.Int32Value type.

1442

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

},

},

],

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

1447

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

1448

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

1449

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

1450

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

1451

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

Thomas Coffee

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

[diff] [blame]

1452

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1453

],

1454

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

1455

"A String",

1456

],

1457

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

1458

"options": [ # The protocol buffer options.

1459

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

1460

# enumeration, etc.

1461

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

1462

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

1463

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

1464

# `"google.api.http"`.

1465

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

1466

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

1467

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

1468

# value using the google.protobuf.Int32Value type.

1469

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

},

},

],

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

1474

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

1475

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

1476

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

1477

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

},

},

],

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

1482

#

1483

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

1484

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

1485

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

1486

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

1487

#

1488

# monitored_resources:

1489

# - type: library.googleapis.com/branch

1490

# labels:

1491

# - key: /city

1492

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

1493

# - key: /name

1494

# description: The name of the branch.

1495

# logs:

1496

# - name: activity_history

1497

# labels:

1498

# - key: /customer_id

1499

# - name: purchase_history

1500

# logging:

1501

# producer_destinations:

1502

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

1507

# - monitored_resource: library.googleapis.com/branch

1508

# logs:

1509

# - activity_history

1510

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

1511

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

1512

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

1513

# one consumer destination.

1514

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

1515

# or the consumer project).

1516

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

1517

# Service.monitored_resources section.

1518

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

1519

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

1520

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

1521

# the service name followed by "/".

"A String",

],

},

],

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

1527

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

1528

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

1529

# one producer destination.

1530

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

1531

# or the consumer project).

1532

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

1533

# Service.monitored_resources section.

1534

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

1535

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

1536

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

1537

# the service name followed by "/".

"A String",

],

},

],

},

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

1544

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

1545

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

1546

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

1547

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

1548

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

1549

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

1550

#

1551

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

1552

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

1553

# by the API.

1554

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

1555

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

1556

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

1557

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

1558

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

1559

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

1560

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

1561

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

1562

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

1563

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

1564

{ # A description of a label.

1565

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

1566

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

1567

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

1568

},

1569

],

1570

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

1571

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

1572

# The maximum length of this value is 256 characters.

1573

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

1574

# be used in documentation.

1575

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

1576

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

1577

# without any article or other determiners. For example,

1578

# `"Google Cloud SQL Database"`.

1579

},

1580

],

1581

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

1582

#

1583

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

1584

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

1585

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

1586

# to both producer and consumer projects, whereas the

1587

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

1588

# consumer project.

1589

#

1590

# monitored_resources:

1591

# - type: library.googleapis.com/branch

1592

# labels:

1593

# - key: /city

1594

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

1595

# - key: /name

1596

# description: The name of the branch.

1597

# metrics:

1598

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1603

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1608

# monitoring:

1609

# producer_destinations:

1610

# - monitored_resource: library.googleapis.com/branch

1611

# metrics:

1612

# - library.googleapis.com/book/returned_count

1613

# consumer_destinations:

1614

# - monitored_resource: library.googleapis.com/branch

1615

# metrics:

1616

# - library.googleapis.com/book/returned_count

1617

# - library.googleapis.com/book/overdue_count

1618

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

1619

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

1620

# appear in multiple monitoring destinations if different aggregations are

1621

# needed for different sets of metrics associated with that monitored

1622

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

1623

# in the Monitoring configuration.

1624

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

1625

# or the consumer project).

1626

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

1627

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

1628

"A String",

1629

],

1630

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

1631

# Service.monitored_resources section.

1632

},

1633

],

1634

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

1635

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

1636

# appear in multiple monitoring destinations if different aggregations are

1637

# needed for different sets of metrics associated with that monitored

1638

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

1639

# in the Monitoring configuration.

1640

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

1641

# or the consumer project).

1642

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

1643

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

1644

"A String",

1645

],

1646

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

1647

# Service.monitored_resources section.

Jon Wayne Parrott

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

[diff] [blame]

1648

},

1649

],

1650

},

Bu Sun Kim

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

[diff] [blame]

1651

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

1652

#

1653

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

1654

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

1655

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

1656

# change the names of the system parameters.

1657

"rules": [ # Define system parameters.

Bu Sun Kim

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

[diff] [blame]

1658

#

Bu Sun Kim

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

[diff] [blame]

1659

# The parameters defined here will override the default parameters

1660

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

1661

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

1662

# and names is implementation-dependent.

1663

#

1664

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1672

#

1673

#

1674

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1679

# parameters:

1680

# - name: api_key

1681

# http_header: Api-Key1

1682

# - name: api_key

1683

# http_header: Api-Key2

1684

#

1685

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

1686

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

1687

# methods.

1688

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

1689

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

1690

# names are used the behavior is implementation-dependent.

1691

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

1692

# parameter-dependent.

1693

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

1694

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

1695

# is implementation-dependent.

Bu Sun Kim

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

[diff] [blame]

1696

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

1697

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

1698

# sensitive.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1699

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

1700

# insensitive.

Jon Wayne Parrott

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

[diff] [blame]

1701

},

Bu Sun Kim

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

[diff] [blame]

1702

],

1703

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

1704

# methods in all APIs.

1705

#

1706

# Refer to selector for syntax details.

1707

},

1708

],

1709

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1710

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

1711

# usage.

1712

#

1713

# The metric based quota configuration works this way:

1714

# - The service configuration defines a set of metrics.

1715

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

1716

# corresponding costs.

1717

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

1718

# quota checks at runtime.

1719

#

1720

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

1726

# metric: library.googleapis.com/write_calls

1727

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

# values:

# STANDARD: 10000

#

#

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

1733

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

1734

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

1735

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1740

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

1741

# metric_costs:

1742

# library.googleapis.com/write_calls: 2

1743

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

1744

# metric_costs:

1745

# library.googleapis.com/write_calls: 1

1746

#

1747

# Corresponding Metric definition:

1748

#

1749

# metrics:

1750

# - name: library.googleapis.com/read_calls

1751

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1756

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

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

1761

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

1762

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

1763

# type combination defined within a `QuotaGroup`.

1764

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

1765

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

1766

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

1767

# display name generated from the configuration.

1768

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

1769

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

1770

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

1771

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

Bu Sun Kim

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

[diff] [blame]

1772

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1773

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

1774

# indicating unlimited maximum quota.

Bu Sun Kim

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

[diff] [blame]

1775

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1776

# Used by group-based quotas only.

1777

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

Bu Sun Kim

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

[diff] [blame]

1778

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1779

# Used by group-based quotas only.

1780

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

1781

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

1782

# billed amount when billing is enabled.

1783

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

1784

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

1785

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

Bu Sun Kim

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

[diff] [blame]

1786

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1787

# Used by group-based quotas only.

1788

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

1789

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

1790

# backend system.

Bu Sun Kim

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

[diff] [blame]

1791

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1792

# Here are some examples:

1793

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

1794

#

1795

# Note: the order of unit components is insignificant.

1796

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

1797

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

1798

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

1799

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

1800

#

1801

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

1802

# are provisioning quota to selected consumers and blocking others.

1803

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

1804

# negative values are allowed.

1805

#

1806

# Used by group-based quotas only.

1807

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

1808

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

1809

# specified unit. Currently only STANDARD is supported.

1810

"a_key": "A String",

1811

},

1812

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

1813

#

1814

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

1815

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

1816

#

1817

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

1818

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

1819

# the same metric will be checked together during runtime. The metric must be

1820

# defined within the service config.

1821

"description": "A String", # Optional. User-visible, extended description for this quota limit.

1822

# Should be used only when more context is needed to understand this limit

1823

# than provided by the limit's display name (see: `display_name`).

1824

},

1825

],

1826

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

1827

# or more metrics.

1828

{ # Bind API methods to metrics. Binding a method to a metric causes that

1829

# metric's configured quota behaviors to apply to the method call.

1830

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

1831

# cost applied to each metric.

1832

#

1833

# The key of the map is the metric name, and the values are the amount

1834

# increased for the metric against which the quota limits are defined.

1835

# The value must not be negative.

1836

"a_key": "A String",

1837

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1838

"selector": "A String", # Selects the methods to which this rule applies.

1839

#

1840

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1841

},

1842

],

1843

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1844

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1845

#

1846

# Example:

1847

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

1853

# - google.rpc.context.OriginContext

1854

#

1855

# The above specifies that all methods in the API request

1856

# `google.rpc.context.ProjectContext` and

1857

# `google.rpc.context.OriginContext`.

1858

#

1859

# Available context types are defined in package

1860

# `google.rpc.context`.

1861

#

1862

# This also provides mechanism to whitelist any protobuf message extension that

1863

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

1864

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

1865

# 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"

1873

# allowed_request_extensions:

1874

# - google.foo.v1.NewExtension

1875

# allowed_response_extensions:

1876

# - google.foo.v1.NewExtension

1877

#

1878

# You can also specify extension ID instead of fully qualified extension name

1879

# here.

1880

"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]

1881

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1882

# **NOTE:** All service configuration rules follow "last one wins" order.

1883

{ # A context rule provides information about the context for an individual API

1884

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1885

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1886

# side channel from client to backend.

1887

"A String",

1888

],

1889

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1890

# side channel from backend to client.

1891

"A String",

1892

],

1893

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1894

#

1895

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1896

"requested": [ # A list of full type names of requested contexts.

1897

"A String",

1898

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1899

"provided": [ # A list of full type names of provided contexts.

1900

"A String",

1901

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1902

},

1903

],

1904

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1905

"producerProjectId": "A String", # The Google project that owns this service.

1906

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

1907

"rules": [ # A list of API backend rules that apply to individual API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1908

#

1909

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1910

{ # A backend rule provides configuration for an individual API element.

1911

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

1912

# operation. The default is no deadline.

1913

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

1914

# value lower than this will be rejected.

1915

"address": "A String", # The address of the API backend.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1916

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1917

# The scheme is used to determine the backend protocol and security.

1918

# The following schemes are accepted:

1919

#

1920

# 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

1927

# may cause constrasting behaviors across platforms.

1928

#

1929

# If the port is unspecified, the default is:

1930

# - 80 for schemes without TLS

1931

# - 443 for schemes with TLS

1932

#

1933

# For HTTP backends, use protocol

1934

# to specify the protocol version.

1935

"pathTranslation": "A String",

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1936

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1937

#

1938

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1939

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

1940

# This ID token will be added in the HTTP "authorization" header, and sent

1941

# to the backend.

1942

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

1943

# original "Authorization" HTTP header will be preserved. If the header is

1944

# used to carry the original token and is expected by the backend, this

1945

# field must be set to true to preserve the header.

1946

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

1947

# varies based on the request protocol and deployment environment.

1948

"protocol": "A String", # The protocol used for sending a request to the backend.

1949

# The supported values are "http/1.1" and "h2".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1950

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1951

# The default value is inferred from the scheme in the

1952

# address field:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1953

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1959

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1960

# For secure HTTP backends (https://) that support HTTP/2, set this field

1961

# to "h2" for improved performance.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1962

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1963

# Configuring this field to non-default values is only supported for secure

1964

# HTTP backends. This field will be ignored for all other backends.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1965

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

1966

# See

1967

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

1968

# for more details on the supported values.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

],

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1981

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1982

{ # `Service` is the root object of Google service configuration schema. It

1983

# describes basic information about a service, such as the name and the

1984

# title, and delegates other aspects to sub-sections. Each sub-section is

1985

# either a proto message or a repeated proto message that configures a

1986

# 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]

1991

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1992

# name: calendar.googleapis.com

1993

# title: Google Calendar API

1994

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1995

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1996

# authentication:

1997

# providers:

1998

# - id: google_calendar_auth

1999

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2000

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2001

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2002

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2003

# requirements:

2004

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2005

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2006

# service controller handles features like abuse, quota, billing, logging,

2007

# monitoring, etc.

2008

"environment": "A String", # The service control environment to use. If empty, no control plane

2009

# feature (like quota and billing) will be enabled.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2010

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2011

"types": [ # A list of all proto message types included in this API service.

2012

# Types referenced directly or indirectly by the `apis` are

2013

# automatically included. Messages which are not referenced but

2014

# shall be included, such as types used by the `google.protobuf.Any` type,

2015

# should be listed here by name. Example:

2016

#

2017

# types:

2018

# - name: google.protobuf.Int32

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2019

{ # A protocol buffer message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2020

"fields": [ # The list of fields.

2021

{ # A single field of a message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2022

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2023

"name": "A String", # The field name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2024

"kind": "A String", # The field type.

2025

"jsonName": "A String", # The field JSON name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2026

"cardinality": "A String", # The field cardinality.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2027

"options": [ # The protocol buffer options.

2028

{ # A protocol buffer option, which can be attached to a message, field,

2029

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2030

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2031

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2032

# For custom options, it should be the fully-qualified name. For example,

2033

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2034

"value": { # The option's value packed in an Any message. If the value is a primitive,

2035

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2036

# should be used. If the value is an enum, it should be stored as an int32

2037

# value using the google.protobuf.Int32Value type.

2038

"a_key": "", # Properties of the object. Contains field @type with type URL.

2039

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2040

},

2041

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2042

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2043

"packed": True or False, # Whether to use alternative packed wire representation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2044

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2045

# types. The first type has index 1; zero means the type is not in the list.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2046

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2047

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2048

},

2049

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2050

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2051

"A String",

2052

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2053

"name": "A String", # The fully qualified message name.

2054

"options": [ # The protocol buffer options.

2055

{ # A protocol buffer option, which can be attached to a message, field,

2056

# enumeration, etc.

2057

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2058

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2059

# For custom options, it should be the fully-qualified name. For example,

2060

# `"google.api.http"`.

2061

"value": { # The option's value packed in an Any message. If the value is a primitive,

2062

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2063

# should be used. If the value is an enum, it should be stored as an int32

2064

# value using the google.protobuf.Int32Value type.

2065

"a_key": "", # Properties of the object. Contains field @type with type URL.

2066

},

2067

},

2068

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2069

"syntax": "A String", # The source syntax.

2070

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2071

# protobuf element, like the file in which it is defined.

2072

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2073

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2074

},

2075

},

2076

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2077

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

2078

"sourceFiles": [ # All files used during config generation.

2079

{

2080

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

2085

# service, such as `calendar.googleapis.com`. The service name

2086

# typically goes through DNS verification to make sure the owner

2087

# of the service also owns the DNS name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2088

"title": "A String", # The product title for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2089

"logs": [ # Defines the logs used by this service.

2090

{ # A description of a log type. Example in YAML format:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2091

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2092

# - name: library.googleapis.com/activity_history

2093

# description: The history of borrowing and returning library items.

2094

# display_name: Activity

2095

# labels:

2096

# - key: /customer_id

2097

# description: Identifier of a library customer

2098

"labels": [ # The set of labels that are available to describe a specific log entry.

2099

# Runtime requests that contain labels not specified here are

2100

# considered invalid.

2101

{ # A description of a label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2102

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2103

"key": "A String", # The label key.

2104

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2105

},

2106

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2107

"description": "A String", # A human-readable description of this log. This information appears in

2108

# the documentation and can contain details.

2109

"displayName": "A String", # The human-readable name for this log. This information appears on

2110

# the user interface and should be concise.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2111

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2112

# include the following characters: upper- and lower-case alphanumeric

2113

# characters [A-Za-z0-9], and punctuation characters including

2114

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2115

},

2116

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2117

"metrics": [ # Defines the metrics used by this service.

2118

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2119

# deleting or altering it stops data collection and makes the metric type's

2120

# existing data unusable.

2121

"type": "A String", # The metric type, including its DNS name prefix. The type is not

2122

# URL-encoded. All user-defined metric types have the DNS name

2123

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

2124

# use a natural hierarchical grouping. For example:

2125

#

2126

# "custom.googleapis.com/invoice/paid/amount"

2127

# "external.googleapis.com/prometheus/up"

2128

# "appengine.googleapis.com/http/server/response_latencies"

2129

"labels": [ # The set of labels that can be used to describe a specific

2130

# instance of this metric type. For example, the

2131

# `appengine.googleapis.com/http/server/response_latencies` metric

2132

# type has a label for the HTTP response code, `response_code`, so

2133

# you can look at latencies for successful responses or just

2134

# for responses that failed.

2135

{ # A description of a label.

2136

"valueType": "A String", # The type of data that can be assigned to the label.

2137

"key": "A String", # The label key.

2138

"description": "A String", # A human-readable description for the label.

2139

},

2140

],

2141

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2142

"monitoredResourceTypes": [ # Read-only. If present, then a time

2143

# series, which is identified partially by

2144

# a metric type and a MonitoredResourceDescriptor, that is associated

2145

# with this metric type can only be associated with one of the monitored

2146

# resource types listed here.

2147

"A String",

2148

],

2149

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2150

# Use sentence case without an ending period, for example "Request count".

2151

# This field is optional but it is recommended to be set for any metrics

2152

# associated with user-visible concepts, such as Quota.

2153

"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.

2154

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

2155

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

2156

# age are guaranteed to be ingested and available to be read, excluding

2157

# data loss due to errors.

2158

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

2159

# periodically, consecutive data points are stored at this time interval,

2160

# excluding data loss due to errors. Metrics with a higher granularity have

2161

# a smaller sampling period.

2162

},

2163

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

2164

# Some combinations of `metric_kind` and `value_type` might not be supported.

2165

"unit": "A String", # The units in which the metric value is reported. It is only applicable

2166

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

2167

# defines the representation of the stored metric values.

2168

#

2169

# Different systems may scale the values to be more easily displayed (so a

2170

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

2171

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

2172

# `KBy`, then the value of the metric is always in thousands of bytes, no

2173

# matter how it may be displayed..

2174

#

2175

# If you want a custom metric to record the exact number of CPU-seconds used

2176

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

2177

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

2178

# CPU-seconds, then the value is written as `12005`.

2179

#

2180

# Alternatively, if you want a custom metric to record data in a more

2181

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

2182

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

2183

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

2184

#

2185

# The supported units are a subset of [The Unified Code for Units of

2186

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2187

#

2188

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

2206

# * `Y` yotta (10^24)

2207

#

2208

# * `m` milli (10^-3)

2209

# * `u` micro (10^-6)

2210

# * `n` nano (10^-9)

2211

# * `p` pico (10^-12)

2212

# * `f` femto (10^-15)

2213

# * `a` atto (10^-18)

2214

# * `z` zepto (10^-21)

2215

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

#

# **Grammar**

#

# The grammar also includes these connectors:

2226

#

2227

# * `/` division or ratio (as an infix operator). For examples,

2228

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

2229

# have `/s` in a metric `unit`; rates should always be computed at

2230

# query time from the underlying cumulative or delta value).

2231

# * `.` multiplication or composition (as an infix operator). For

2232

# examples, `GBy.d` or `k{watt}.h`.

2233

#

2234

# The grammar for a unit is as follows:

2235

#

2236

# Expression = Component { "." Component } { "/" Component } ;

2237

#

2238

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

2248

# is used alone, then the unit is equivalent to `1`. For examples,

2249

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

2250

# * `NAME` is a sequence of non-blank printable ASCII characters not

2251

# containing `{` or `}`.

2252

# * `1` represents a unitary [dimensionless

2253

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

2254

# as in `1/s`. It is typically used when none of the basic units are

2255

# appropriate. For example, "new users per day" can be represented as

2256

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

2257

# users). Alternatively, "thousands of page views per day" would be

2258

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

2259

# value of `5.3` would mean "5300 page views per day").

2260

# * `%` represents dimensionless value of 1/100, and annotates values giving

2261

# a percentage (so the metric values are typically in the range of 0..100,

2262

# and a metric value `3` means "3 percent").

2263

# * `10^2.%` indicates a metric contains a ratio, typically in the range

2264

# 0..1, that will be multiplied by 100 and displayed as a percentage

2265

# (so a metric value `0.03` means "3 percent").

2266

"launchStage": "A String", # Optional. The launch stage of the metric definition.

2267

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

2268

# Some combinations of `metric_kind` and `value_type` might not be supported.

2269

"name": "A String", # The resource name of the metric descriptor.

2270

},

2271

],

2272

"enums": [ # A list of all enum types included in this API service. Enums

2273

# referenced directly or indirectly by the `apis` are automatically

2274

# included. Enums which are not referenced but shall be included

2275

# should be listed here by name. Example:

2276

#

2277

# enums:

2278

# - name: google.someapi.v1.SomeEnum

2279

{ # Enum type definition.

2280

"options": [ # Protocol buffer options.

2281

{ # A protocol buffer option, which can be attached to a message, field,

2282

# enumeration, etc.

2283

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2284

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2285

# For custom options, it should be the fully-qualified name. For example,

2286

# `"google.api.http"`.

2287

"value": { # The option's value packed in an Any message. If the value is a primitive,

2288

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2289

# should be used. If the value is an enum, it should be stored as an int32

2290

# value using the google.protobuf.Int32Value type.

2291

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2296

"syntax": "A String", # The source syntax.

2297

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2298

# protobuf element, like the file in which it is defined.

2299

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2300

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2301

},

2302

"enumvalue": [ # Enum value definitions.

2303

{ # Enum value definition.

2304

"name": "A String", # Enum value name.

2305

"number": 42, # Enum value number.

2306

"options": [ # Protocol buffer options.

2307

{ # A protocol buffer option, which can be attached to a message, field,

2308

# enumeration, etc.

2309

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2310

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2311

# For custom options, it should be the fully-qualified name. For example,

2312

# `"google.api.http"`.

2313

"value": { # The option's value packed in an Any message. If the value is a primitive,

2314

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2315

# should be used. If the value is an enum, it should be stored as an int32

2316

# value using the google.protobuf.Int32Value type.

2317

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

},

],

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

2326

#

2327

# Example for an API targeted for external use:

2328

#

2329

# name: calendar.googleapis.com

2330

# authentication:

2331

# providers:

2332

# - id: google_calendar_auth

2333

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2334

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

2339

"rules": [ # A list of authentication rules that apply to individual API methods.

2340

#

2341

# **NOTE:** All service configuration rules follow "last one wins" order.

2342

{ # Authentication rules for the service.

2343

#

2344

# By default, if a method has any authentication requirements, every request

2345

# must include a valid credential matching one of the requirements.

2346

# It's an error to include more than one kind of credential in a single

2347

# request.

2348

#

2349

# If a method doesn't have any auth requirements, request credentials will be

2350

# ignored.

2351

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

2352

# there are scopes defined for "Read-only access to Google Calendar" and

2353

# "Access to Cloud Platform". Users can consent to a scope for an application,

2354

# giving it permission to access that data on their behalf.

2355

#

2356

# OAuth scope specifications should be fairly coarse grained; a user will need

2357

# to see and understand the text description of what your scope means.

2358

#

2359

# In most cases: use one or at most two OAuth scopes for an entire family of

2360

# products. If your product has multiple APIs, you should probably be sharing

2361

# the OAuth scope across all of those APIs.

2362

#

2363

# When you need finer grained OAuth consent screens: talk with your product

2364

# management about how developers will use them in practice.

2365

#

2366

# Please note that even though each of the canonical scopes is enough for a

2367

# request to be accepted and passed to the backend, a request can still fail

2368

# due to the backend requiring additional scopes or permissions.

2369

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

2370

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

2375

# https://www.googleapis.com/auth/calendar.read

2376

},

2377

"requirements": [ # Requirements for additional authentication providers.

2378

{ # User-defined authentication requirements, including support for

2379

# [JSON Web Token

2380

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

2381

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

2382

# implemented and accepted in all the runtime components.

2383

#

2384

# The list of JWT

2385

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2386

# that are allowed to access. A JWT containing any of these audiences will

2387

# be accepted. When this setting is absent, only JWTs with audience

2388

# "https://Service_name/API_name"

2389

# will be accepted. For example, if no audiences are in the setting,

2390

# LibraryService API will only accept JWTs with the following audience

2391

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2396

# bookstore_web.apps.googleusercontent.com

2397

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

2402

},

2403

],

2404

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

2405

"selector": "A String", # Selects the methods to which this rule applies.

2406

#

2407

# Refer to selector for syntax details.

2408

},

2409

],

2410

"providers": [ # Defines a set of authentication providers that a service supports.

2411

{ # Configuration for an authentication provider, including support for

2412

# [JSON Web Token

2413

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

2414

"audiences": "A String", # The list of JWT

2415

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2416

# that are allowed to access. A JWT containing any of these audiences will

2417

# be accepted. When this setting is absent, JWTs with audiences:

2418

# - "https://[service.name]/[google.protobuf.Api.name]"

2419

# - "https://[service.name]/"

2420

# will be accepted.

2421

# For example, if no audiences are in the setting, LibraryService API will

2422

# accept JWTs with the following audiences:

2423

# -

2424

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

2425

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2430

# bookstore_web.apps.googleusercontent.com

2431

"jwtLocations": [ # Defines the locations to extract the JWT.

2432

#

2433

# JWT locations can be either from HTTP headers or URL query parameters.

2434

# The rule is that the first match wins. The checking order is: checking

2435

# all headers first, then URL query parameters.

2436

#

2437

# If not specified, default to use following 3 locations:

2438

# 1) Authorization: Bearer

2439

# 2) x-goog-iap-jwt-assertion

2440

# 3) access_token query parameter

2441

#

2442

# Default locations can be specified as followings:

2443

# jwt_locations:

2444

# - header: Authorization

2445

# value_prefix: "Bearer "

2446

# - header: x-goog-iap-jwt-assertion

2447

# - query: access_token

2448

{ # Specifies a location to extract JWT from an API request.

2449

"query": "A String", # Specifies URL query parameter name to extract JWT token.

2450

"header": "A String", # Specifies HTTP header name to extract JWT token.

2451

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

2452

# Only applies to "in" header type. Must be empty for "in" query type.

2453

# If not empty, the header value has to match (case sensitive) this prefix.

2454

# If not matched, JWT will not be extracted. If matched, JWT will be

2455

# extracted after the prefix is removed.

2456

#

2457

# For example, for "Authorization: Bearer {JWT}",

2458

# value_prefix="Bearer " with a space at the end.

2459

},

2460

],

2461

"issuer": "A String", # Identifies the principal that issued the JWT. See

2462

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

2463

# Usually a URL or an email address.

2464

#

2465

# Example: https://securetoken.google.com

2466

# Example: 1234567-compute@developer.gserviceaccount.com

2467

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

2468

# `AuthRequirement.provider_id`.

2469

#

2470

# Example: "bookstore_auth".

2471

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

2472

# [OpenID

2473

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

2474

# Optional if the key set document:

2475

# - can be retrieved from

2476

# [OpenID

2477

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

2478

# the issuer.

2479

# - can be inferred from the email domain of the issuer (e.g. a Google

2480

# service account).

2481

#

2482

# Example: https://www.googleapis.com/oauth2/v1/certs

2483

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

2484

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

},

],

},

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2489

#

2490

# Example:

2491

# <pre><code>documentation:

2492

# summary: >

2493

# The Google Calendar API gives access

2494

# to most calendar features.

2495

# pages:

2496

# - name: Overview

2497

# content: &#40;== include google/foo/overview.md ==&#41;

2498

# - name: Tutorial

2499

# content: &#40;== include google/foo/tutorial.md ==&#41;

2500

# subpages;

2501

# - name: Java

2502

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

2503

# rules:

2504

# - selector: google.calendar.Calendar.Get

2505

# description: >

2506

# ...

2507

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2512

# standard markdown features, definition lists, tables and fenced

2513

# code blocks are supported. Section headers can be provided and are

2514

# interpreted relative to the section nesting of the context where

2515

# a documentation fragment is embedded.

2516

#

2517

# Documentation from the IDL is merged with documentation defined

2518

# via the config at normalization time, where documentation provided

2519

# by config rules overrides IDL provided.

2520

#

2521

# A number of constructs specific to the API platform are supported

2522

# in documentation text.

2523

#

2524

# In order to reference a proto element, the following

2525

# notation can be used:

2526

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

2527

# To override the display text used for the link, this can be used:

2528

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

2529

# Text can be excluded from doc using the following notation:

2530

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

2531

#

2532

# A few directives are available in documentation. Note that

2533

# directives must appear on a single line to be properly

2534

# identified. The `include` directive includes a markdown file from

2535

# an external source:

2536

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

2537

# The `resource_for` directive marks a message to be the resource of

2538

# a collection in REST view. If it is not specified, tools attempt

2539

# to infer the resource from the operations in a collection:

2540

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

2541

# The directive `suppress_warning` does not directly affect documentation

2542

# and is documented together with service config validation.

2543

"documentationRootUrl": "A String", # The URL to the root of documentation.

2544

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

2545

# from the yaml file) is not suitable. This can be seen in any fully

2546

# specified service urls as well as sections that show a base that other

2547

# urls are relative to.

2548

"rules": [ # A list of documentation rules that apply to individual API elements.

2549

#

2550

# **NOTE:** All service configuration rules follow "last one wins" order.

2551

{ # A documentation rule provides information about individual API elements.

2552

"description": "A String", # Description of the selected API(s).

2553

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

2554

# an element is marked as `deprecated`.

2555

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2556

# qualified name of the element which may end in "*", indicating a wildcard.

2557

# Wildcards are only allowed at the end and for a whole component of the

2558

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

2559

# wildcard will match one or more components. To specify a default for all

2560

# applicable elements, the whole pattern "*" is used.

2561

},

2562

],

2563

"pages": [ # The top level pages for the documentation set.

2564

{ # Represents a documentation page. A page can contain subpages to represent

2565

# nested documentation set structure.

2566

"name": "A String", # The name of the page. It will be used as an identity of the page to

2567

# generate URI of the page, text of the link to this page in navigation,

2568

# etc. The full page name (start from the root page name to this page

2569

# concatenated with `.`) can be used as reference to the page in your

2570

# documentation. For example:

2571

# <pre><code>pages:

2572

# - name: Tutorial

2573

# content: &#40;== include tutorial.md ==&#41;

2574

# subpages:

2575

# - name: Java

2576

# content: &#40;== include tutorial_java.md ==&#41;

2577

# </code></pre>

2578

# You can reference `Java` page using Markdown reference link syntax:

2579

# `Java`.

2580

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2581

# honored in the generated docset.

2582

# Object with schema name: Page

2583

],

2584

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

2585

# ==&#41;</code> to include content from a Markdown file.

2586

},

2587

],

2588

"summary": "A String", # A short summary of what the service does. Can only be provided by

2589

# plain text.

2590

"overview": "A String", # Declares a single overview page. For example:

2591

# <pre><code>documentation:

2592

# summary: ...

2593

# overview: &#40;== include overview.md ==&#41;

2594

# </code></pre>

2595

# This is a shortcut for the following declaration (using pages style):

2596

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

2601

# </code></pre>

2602

# Note: you cannot specify both `overview` field and `pages` field.

2603

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2604

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2605

# of the google.protobuf.Api needs to be provided by the configuration

2606

# author, as the remaining fields will be derived from the IDL during the

2607

# normalization process. It is an error to specify an API interface here

2608

# which cannot be resolved against the associated IDL files.

2609

{ # Api is a light-weight descriptor for an API Interface.

2610

#

2611

# Interfaces are also described as "protocol buffer services" in some contexts,

2612

# such as by the "service" keyword in a .proto file, but they are different

2613

# from API Services, which represent a concrete implementation of an interface

2614

# as opposed to simply a description of methods and bindings. They are also

2615

# sometimes simply referred to as "APIs" in other contexts, such as the name of

2616

# this message itself. See https://cloud.google.com/apis/design/glossary for

2617

# detailed terminology.

2618

"options": [ # Any metadata attached to the interface.

2619

{ # A protocol buffer option, which can be attached to a message, field,

2620

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2621

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2622

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2623

# For custom options, it should be the fully-qualified name. For example,

2624

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2625

"value": { # The option's value packed in an Any message. If the value is a primitive,

2626

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2627

# should be used. If the value is an enum, it should be stored as an int32

2628

# value using the google.protobuf.Int32Value type.

2629

"a_key": "", # Properties of the object. Contains field @type with type URL.

2630

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2631

},

2632

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2633

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2634

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2635

# message.

2636

# protobuf element, like the file in which it is defined.

2637

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2638

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2639

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2640

"mixins": [ # Included interfaces. See Mixin.

2641

{ # Declares an API Interface to be included in this interface. The including

2642

# interface must redeclare all the methods from the included interface, but

2643

# documentation and options are inherited as follows:

2644

#

2645

# - If after comment and whitespace stripping, the documentation

2646

# string of the redeclared method is empty, it will be inherited

2647

# from the original method.

2648

#

2649

# - Each annotation belonging to the service config (http,

2650

# visibility) which is not set in the redeclared method will be

2651

# inherited.

2652

#

2653

# - If an http annotation is inherited, the path pattern will be

2654

# modified as follows. Any version prefix will be replaced by the

2655

# version of the including interface plus the root path if

2656

# specified.

2657

#

2658

# Example of a simple mixin:

2659

#

2660

# package google.acl.v1;

2661

# service AccessControl {

2662

# // Get the underlying ACL object.

2663

# rpc GetAcl(GetAclRequest) returns (Acl) {

2664

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2669

# service Storage {

2670

# // rpc GetAcl(GetAclRequest) returns (Acl);

2671

#

2672

# // Get a data record.

2673

# rpc GetData(GetDataRequest) returns (Data) {

2674

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2679

#

2680

# apis:

2681

# - name: google.storage.v2.Storage

2682

# mixins:

2683

# - name: google.acl.v1.AccessControl

2684

#

2685

# The mixin construct implies that all methods in `AccessControl` are

2686

# also declared with same name and request/response types in

2687

# `Storage`. A documentation generator or annotation processor will

2688

# see the effective `Storage.GetAcl` method after inherting

2689

# documentation and annotations as follows:

2690

#

2691

# service Storage {

2692

# // Get the underlying ACL object.

2693

# rpc GetAcl(GetAclRequest) returns (Acl) {

2694

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2700

#

2701

# If the `root` field in the mixin is specified, it should be a

2702

# relative path under which inherited HTTP paths are placed. Example:

2703

#

2704

# apis:

2705

# - name: google.storage.v2.Storage

2706

# mixins:

2707

# - name: google.acl.v1.AccessControl

2708

# root: acls

2709

#

2710

# This implies the following inherited HTTP annotation:

2711

#

2712

# service Storage {

2713

# // Get the underlying ACL object.

2714

# rpc GetAcl(GetAclRequest) returns (Acl) {

2715

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"name": "A String", # The fully qualified name of the interface which is included.

2720

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2721

# are rooted.

2722

},

2723

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2724

"version": "A String", # A version string for this interface. If specified, must have the form

2725

# `major-version.minor-version`, as in `1.10`. If the minor version is

2726

# omitted, it defaults to zero. If the entire version field is empty, the

2727

# major version is derived from the package name, as outlined below. If the

2728

# field is not empty, the version in the package name will be verified to be

2729

# consistent with what is provided here.

2730

#

2731

# The versioning schema uses [semantic

2732

# versioning](http://semver.org) where the major version number

2733

# indicates a breaking change and the minor version an additive,

2734

# non-breaking change. Both version numbers are signals to users

2735

# what to expect from different versions, and should be carefully

2736

# chosen based on the product plan.

2737

#

2738

# The major version is also reflected in the package name of the

2739

# interface, which must end in `v<major-version>`, as in

2740

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2741

# be omitted. Zero major versions must only be used for

2742

# experimental, non-GA interfaces.

2743

"methods": [ # The methods of this interface, in unspecified order.

2744

{ # Method represents a method of an API interface.

2745

"requestTypeUrl": "A String", # A URL of the input message type.

2746

"name": "A String", # The simple name of this method.

2747

"responseStreaming": True or False, # If true, the response is streamed.

2748

"requestStreaming": True or False, # If true, the request is streamed.

2749

"options": [ # Any metadata attached to the method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2750

{ # A protocol buffer option, which can be attached to a message, field,

2751

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2752

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2753

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2754

# For custom options, it should be the fully-qualified name. For example,

2755

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2756

"value": { # The option's value packed in an Any message. If the value is a primitive,

2757

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2758

# should be used. If the value is an enum, it should be stored as an int32

2759

# value using the google.protobuf.Int32Value type.

2760

"a_key": "", # Properties of the object. Contains field @type with type URL.

2761

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2762

},

2763

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2764

"syntax": "A String", # The source syntax of this method.

2765

"responseTypeUrl": "A String", # The URL of the output message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2766

},

2767

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2768

"name": "A String", # The fully qualified name of this interface, including package name

2769

# followed by the interface's simple name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2770

},

2771

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2772

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2773

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2781

# - google.foo.v1.AnotherError

2782

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

2783

"A String",

2784

],

2785

"rules": [ # The list of custom error rules that apply to individual API messages.

2786

#

2787

# **NOTE:** All service configuration rules follow "last one wins" order.

2788

{ # A custom error rule.

2789

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2790

# objects of this type will be filtered when they appear in error payload.

2791

"selector": "A String", # Selects messages to which this rule applies.

2792

#

2793

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2794

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2795

],

2796

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

2797

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

2798

# by the client for tracking purpose. Must be no longer than 63 characters

2799

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

2800

# empty, the server may choose to generate one instead.

2801

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

2802

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

2803

# service. Each requirement is of the form <service.name>/<requirement-id>;

2804

# for example 'serviceusage.googleapis.com/billing-enabled'.

2805

"A String",

2806

],

2807

"rules": [ # A list of usage rules that apply to individual API methods.

2808

#

2809

# **NOTE:** All service configuration rules follow "last one wins" order.

2810

{ # Usage configuration rules for the service.

2811

#

2812

# NOTE: Under development.

2813

#

2814

#

2815

# Use this rule to configure unregistered calls for the service. Unregistered

2816

# calls are calls that do not contain consumer project identity.

2817

# (Example: calls that do not contain an API key).

2818

# By default, API methods do not allow unregistered calls, and each method call

2819

# must be identified by a consumer project identity. Use this rule to

2820

# allow/disallow unregistered calls.

2821

#

2822

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

2828

#

2829

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

2834

# allow_unregistered_calls: true

2835

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2836

# methods in all APIs.

2837

#

2838

# Refer to selector for syntax details.

2839

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

2840

# that don't identify any user or application.

2841

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

2842

# plane features, such as quota and billing, will not be available.

2843

# This flag is used by Google Cloud Endpoints to bypass checks for internal

2844

# methods, such as service health check methods.

2845

},

2846

],

2847

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

2848

# service producer.

2849

#

2850

# Google Service Management currently only supports

2851

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2852

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2853

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2854

# documented in https://cloud.google.com/pubsub/docs/overview.

2855

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

2856

#

2857

#

2858

# Use this field to configure per-product per-project service identity.

2859

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

2864

# display_name: "Cloud XXX Service Agent"

2865

# description: "Used as the identity of Cloud XXX to access resources"

2866

"displayName": "A String", # Optional. A user-specified name for the service account.

2867

# Must be less than or equal to 100 UTF-8 bytes.

2868

"description": "A String", # Optional. A user-specified opaque description of the service account.

2869

# Must be less than or equal to 256 UTF-8 bytes.

2870

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

2871

#

2872

# An example name would be:

2873

# `projects/123456789`

2874

},

2875

},

2876

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2877

# with the same name as the service is automatically generated to service all

2878

# defined APIs.

2879

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2880

# A service may expose any number of endpoints, and all endpoints share the

2881

# same service configuration, such as quota configuration and monitoring

2882

# configuration.

2883

#

2884

# Example service configuration:

2885

#

2886

# name: library-example.googleapis.com

2887

# endpoints:

2888

# # Below entry makes 'google.example.library.v1.Library'

2889

# # API be served from endpoint address library-example.googleapis.com.

2890

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2891

# # it to decide whether the subsequent cross-origin request is

2892

# # allowed to proceed.

2893

# - name: library-example.googleapis.com

2894

# allow_cors: true

2895

"name": "A String", # The canonical name of this endpoint.

2896

"target": "A String", # The specification of an Internet routable address of API frontend that will

2897

# handle requests to this [API

2898

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

2899

# either a valid IPv4 address or a fully-qualified domain name. For example,

2900

# "8.8.8.8" or "myservice.appspot.com".

2901

"allowCors": True or False, # Allowing

2902

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2903

# cross-domain traffic, would allow the backends served from this endpoint to

2904

# receive and respond to HTTP OPTIONS requests. The response will be used by

2905

# the browser to determine whether the subsequent cross-origin request is

2906

# allowed to proceed.

2907

"features": [ # The list of features enabled on this endpoint.

2908

"A String",

2909

],

2910

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2911

# please specify multiple google.api.Endpoint for each of the intended

2912

# aliases.

2913

#

2914

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"configVersion": 42, # The semantic version of the service configuration. The config version

2920

# affects the interpretation of the service configuration. For example,

2921

# certain features are enabled by default for certain config versions.

2922

#

2923

# The latest config version is `3`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2924

"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]

2925

# HttpRule, each specifying the mapping of an RPC method

2926

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2927

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2928

#

2929

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2930

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2931

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2932

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

2933

# more HTTP REST endpoints. It allows developers to build a single API service

2934

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

2935

# APIs](https://github.com/googleapis/googleapis),

2936

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

2937

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

2938

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

2939

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2940

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2941

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

2942

# how different portions of the gRPC request message are mapped to the URL

2943

# path, URL query parameters, and HTTP request body. It also controls how the

2944

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

2945

# typically specified as an `google.api.http` annotation on the gRPC method.

2946

#

2947

# Each mapping specifies a URL path template and an HTTP method. The path

2948

# template may refer to one or more fields in the gRPC request message, as long

2949

# as each field is a non-repeated field with a primitive (non-message) type.

2950

# The path template controls how fields of the request message are mapped to

2951

# the URL path.

2952

#

2953

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2954

#

2955

# service Messaging {

2956

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2957

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2958

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2959

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2960

# }

2961

# }

2962

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2963

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2964

# }

2965

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2966

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2967

# }

2968

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2969

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2970

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2971

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2972

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2973

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2974

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2975

# Any fields in the request message which are not bound by the path template

2976

# automatically become HTTP query parameters if there is no HTTP request body.

2977

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2978

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2979

# service Messaging {

2980

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2981

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2982

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2983

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2984

# }

2985

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2986

# message GetMessageRequest {

2987

# message SubMessage {

2988

# string subfield = 1;

2989

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2990

# string message_id = 1; // Mapped to URL path.

2991

# int64 revision = 2; // Mapped to URL query parameter `revision`.

2992

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2993

# }

2994

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2995

# This enables a HTTP JSON to RPC mapping as below:

2996

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2997

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2998

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2999

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3000

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

3001

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3002

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3003

# Note that fields which are mapped to URL query parameters must have a

3004

# primitive type or a repeated primitive type or a non-repeated message type.

3005

# 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]

3006

# 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]

3007

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3008

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3009

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3010

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3011

# specifies the mapping. Consider a REST update method on the

3012

# message resource collection:

3013

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3014

# service Messaging {

3015

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3016

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3017

# patch: "/v1/messages/{message_id}"

3018

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

3023

# string message_id = 1; // mapped to the URL

3024

# Message message = 2; // mapped to the body

3025

# }

3026

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3027

# The following HTTP JSON to RPC mapping is enabled, where the

3028

# representation of the JSON in the request body is determined by

3029

# protos JSON encoding:

3030

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3031

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3032

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3033

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

3034

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3035

#

3036

# The special name `*` can be used in the body mapping to define that

3037

# every field not bound by the path template should be mapped to the

3038

# request body. This enables the following alternative definition of

3039

# the update method:

3040

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3041

# service Messaging {

3042

# rpc UpdateMessage(Message) returns (Message) {

3043

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3044

# patch: "/v1/messages/{message_id}"

3045

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

3051

# string text = 2;

3052

# }

3053

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3054

#

3055

# The following HTTP JSON to RPC mapping is enabled:

3056

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3057

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3058

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3059

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

3060

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3061

#

3062

# Note that when using `*` in the body mapping, it is not possible to

3063

# 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]

3064

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3065

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3066

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3067

#

3068

# It is possible to define multiple HTTP methods for one RPC by using

3069

# the `additional_bindings` option. Example:

3070

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3071

# service Messaging {

3072

# rpc GetMessage(GetMessageRequest) returns (Message) {

3073

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3074

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3075

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3076

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3077

# }

3078

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3079

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3080

# }

3081

# message GetMessageRequest {

3082

# string message_id = 1;

3083

# string user_id = 2;

3084

# }

3085

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3086

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3087

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3088

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3089

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3090

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

3091

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

3092

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3093

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3094

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3095

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3096

# 1. Leaf request fields (recursive expansion nested messages in the request

3097

# message) are classified into three categories:

3098

# - Fields referred by the path template. They are passed via the URL path.

3099

# - Fields referred by the HttpRule.body. They are passed via the HTTP

3100

# request body.

3101

# - All other fields are passed via the URL query parameters, and the

3102

# parameter name is the field path in the request message. A repeated

3103

# field can be represented as multiple query parameters under the same

3104

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3105

# 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]

3106

# are passed via URL path and HTTP request body.

3107

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

3108

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3109

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3110

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3111

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3112

# Template = "/" Segments [ Verb ] ;

3113

# Segments = Segment { "/" Segment } ;

3114

# Segment = "*" | "**" | LITERAL | Variable ;

3115

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3116

# FieldPath = IDENT { "." IDENT } ;

3117

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3118

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3119

# The syntax `*` matches a single URL path segment. The syntax `**` matches

3120

# zero or more URL path segments, which must be the last part of the URL path

3121

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3122

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3123

# The syntax `Variable` matches part of the URL path as specified by its

3124

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3125

# matches a single path segment, its template may be omitted, e.g. `{var}`

3126

# is equivalent to `{var=*}`.

3127

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3128

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

3129

# contains any reserved character, such characters should be percent-encoded

3130

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3131

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3132

# If a variable contains exactly one path segment, such as `"{var}"` or

3133

# `"{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]

3134

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

3135

# server side does the reverse decoding. Such variables show up in the

3136

# [Discovery

3137

# Document](https://developers.google.com/discovery/v1/reference/apis) as

3138

# `{var}`.

3139

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3140

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

3141

# 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]

3142

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3143

# 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]

3144

# unchanged. Such variables show up in the

3145

# [Discovery

3146

# Document](https://developers.google.com/discovery/v1/reference/apis) as

3147

# `{+var}`.

3148

#

3149

# ## Using gRPC API Service Configuration

3150

#

3151

# gRPC API Service Configuration (service config) is a configuration language

3152

# for configuring a gRPC service to become a user-facing product. The

3153

# service config is simply the YAML representation of the `google.api.Service`

3154

# proto message.

3155

#

3156

# As an alternative to annotating your proto file, you can configure gRPC

3157

# transcoding in your service config YAML files. You do this by specifying a

3158

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

3159

# effect as the proto annotation. This can be particularly useful if you

3160

# have a proto that is reused in multiple services. Note that any transcoding

3161

# specified in the service config will override any matching transcoding

3162

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

3169

# - selector: example.v1.Messaging.GetMessage

3170

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

3175

# proto to JSON conversion must follow the [proto3

3176

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

3177

#

3178

# While the single segment variable follows the semantics of

3179

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3180

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

3181

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

3182

# does not expand special characters like `?` and `#`, which would lead

3183

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

3184

# for multi segment variables.

3185

#

3186

# The path variables **must not** refer to any repeated or mapped field,

3187

# because client libraries are not capable of handling such variable expansion.

3188

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3189

# The path variables **must not** capture the leading "/" character. The reason

3190

# 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]

3191

# character. For consistency, all path variables must share the same behavior.

3192

#

3193

# Repeated message fields must not be mapped to URL query parameters, because

3194

# no client library can support such complicated mapping.

3195

#

3196

# If an API needs to use a JSON array for request or response body, it can map

3197

# the request or response body to a repeated field. However, some gRPC

3198

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3199

"selector": "A String", # Selects a method to which this rule applies.

3200

#

3201

# Refer to selector for syntax details.

3202

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

3203

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

3204

# included in the `pattern` field, such as HEAD, or "*" to leave the

3205

# HTTP method unspecified for this rule. The wild-card rule is useful

3206

# for services that provide content to Web (HTML) clients.

3207

"path": "A String", # The path matched by this custom verb.

3208

"kind": "A String", # The name of this custom HTTP verb.

3209

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3210

"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]

3211

# response body. When omitted, the entire response message will be used

3212

# as the HTTP response body.

3213

#

3214

# NOTE: The referred field must be present at the top-level of the response

3215

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3216

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

3217

# half-duplex streaming method.

3218

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3219

# not contain an `additional_bindings` field themselves (that is,

3220

# the nesting may only be one level deep).

3221

# Object with schema name: HttpRule

3222

],

3223

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

3224

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

3225

# resources.

3226

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3227

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

3228

# body, or `*` for mapping all request fields not captured by the path

3229

# pattern to the HTTP body, or omitted for not having any HTTP request body.

3230

#

3231

# NOTE: the referred field must be present at the top-level of the request

3232

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3233

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

3234

},

3235

],

3236

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

3237

# cases of single segment matches in reserved expansion, where "%2F" will be

3238

# left encoded.

3239

#

3240

# The default behavior is to not decode RFC 6570 reserved characters in multi

3241

# segment matches.

3242

},

3243

"billing": { # Billing related configuration of the service. # Billing configuration.

3244

#

3245

# The following example shows how to configure monitored resources and metrics

3246

# for billing, `consumer_destinations` is the only supported destination and

3247

# the monitored resources need at least one label key

3248

# `cloud.googleapis.com/location` to indicate the location of the billing

3249

# usage, using different monitored resources between monitoring and billing is

3250

# recommended so they can be evolved independently:

3251

#

3252

#

3253

# monitored_resources:

3254

# - type: library.googleapis.com/billing_branch

3255

# labels:

3256

# - key: cloud.googleapis.com/location

3257

# description: |

3258

# Predefined label to support billing location restriction.

3259

# - key: city

3260

# description: |

3261

# Custom label to define the city where the library branch is located

3262

# in.

3263

# - key: name

3264

# description: Custom label to define the name of the library branch.

3265

# metrics:

3266

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

3272

# - monitored_resource: library.googleapis.com/billing_branch

3273

# metrics:

3274

# - library.googleapis.com/book/borrowed_count

3275

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

3276

# There can be multiple consumer destinations per service, each one must have

3277

# a different monitored resource type. A metric can be used in at most

3278

# one consumer destination.

3279

{ # Configuration of a specific billing destination (Currently only support

3280

# bill against consumer project).

3281

"metrics": [ # Names of the metrics to report to this billing destination.

3282

# Each name must be defined in Service.metrics section.

3283

"A String",

3284

],

3285

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3286

# Service.monitored_resources section.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

3291

# It serves similar purpose as [google.api.Service.types], except that

3292

# these types are not needed by user-defined APIs. Therefore, they will not

3293

# show up in the generated discovery doc. This field should only be used

3294

# to define system APIs in ESF.

3295

{ # A protocol buffer message type.

3296

"fields": [ # The list of fields.

3297

{ # A single field of a message type.

3298

"number": 42, # The field number.

3299

"name": "A String", # The field name.

3300

"kind": "A String", # The field type.

3301

"jsonName": "A String", # The field JSON name.

3302

"cardinality": "A String", # The field cardinality.

3303

"options": [ # The protocol buffer options.

3304

{ # A protocol buffer option, which can be attached to a message, field,

3305

# enumeration, etc.

3306

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3307

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3308

# For custom options, it should be the fully-qualified name. For example,

3309

# `"google.api.http"`.

3310

"value": { # The option's value packed in an Any message. If the value is a primitive,

3311

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3312

# should be used. If the value is an enum, it should be stored as an int32

3313

# value using the google.protobuf.Int32Value type.

3314

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3319

"packed": True or False, # Whether to use alternative packed wire representation.

3320

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3321

# types. The first type has index 1; zero means the type is not in the list.

3322

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3323

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3324

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3325

],

3326

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3327

"A String",

3328

],

3329

"name": "A String", # The fully qualified message name.

3330

"options": [ # The protocol buffer options.

3331

{ # A protocol buffer option, which can be attached to a message, field,

3332

# enumeration, etc.

3333

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3334

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3335

# For custom options, it should be the fully-qualified name. For example,

3336

# `"google.api.http"`.

3337

"value": { # The option's value packed in an Any message. If the value is a primitive,

3338

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3339

# should be used. If the value is an enum, it should be stored as an int32

3340

# value using the google.protobuf.Int32Value type.

3341

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"syntax": "A String", # The source syntax.

3346

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3347

# protobuf element, like the file in which it is defined.

3348

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3349

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"logging": { # Logging configuration of the service. # Logging configuration.

3354

#

3355

# The following example shows how to configure logs to be sent to the

3356

# producer and consumer projects. In the example, the `activity_history`

3357

# log is sent to both the producer and consumer projects, whereas the

3358

# `purchase_history` log is only sent to the producer project.

3359

#

3360

# monitored_resources:

3361

# - type: library.googleapis.com/branch

3362

# labels:

3363

# - key: /city

3364

# description: The city where the library branch is located in.

3365

# - key: /name

3366

# description: The name of the branch.

3367

# logs:

3368

# - name: activity_history

3369

# labels:

3370

# - key: /customer_id

3371

# - name: purchase_history

3372

# logging:

3373

# producer_destinations:

3374

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

3379

# - monitored_resource: library.googleapis.com/branch

3380

# logs:

3381

# - activity_history

3382

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

3383

# There can be multiple consumer destinations, each one must have a

3384

# different monitored resource type. A log can be used in at most

3385

# one consumer destination.

3386

{ # Configuration of a specific logging destination (the producer project

3387

# or the consumer project).

3388

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

3389

# Service.monitored_resources section.

3390

"logs": [ # Names of the logs to be sent to this destination. Each name must

3391

# be defined in the Service.logs section. If the log name is

3392

# not a domain scoped name, it will be automatically prefixed with

3393

# the service name followed by "/".

"A String",

],

},

],

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3399

# There can be multiple producer destinations, each one must have a

3400

# different monitored resource type. A log can be used in at most

3401

# one producer destination.

3402

{ # Configuration of a specific logging destination (the producer project

3403

# or the consumer project).

3404

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

3405

# Service.monitored_resources section.

3406

"logs": [ # Names of the logs to be sent to this destination. Each name must

3407

# be defined in the Service.logs section. If the log name is

3408

# not a domain scoped name, it will be automatically prefixed with

3409

# the service name followed by "/".

"A String",

],

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3416

# by the Service.monitoring and Service.logging configurations.

3417

{ # An object that describes the schema of a MonitoredResource object using a

3418

# type name and a set of labels. For example, the monitored resource

3419

# descriptor for Google Compute Engine VM instances has a type of

3420

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3421

# `"zone"` to identify particular VM instances.

3422

#

3423

# Different APIs can support different monitored resource types. APIs generally

3424

# provide a `list` method that returns the monitored resource descriptors used

3425

# by the API.

3426

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

3427

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3428

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3429

# {type} is the value of the `type` field in this object and

3430

# {project_id} is a project ID that provides API-specific context for

3431

# accessing the type. APIs that do not use project information can use the

3432

# resource name format `"monitoredResourceDescriptors/{type}"`.

3433

"labels": [ # Required. A set of labels used to describe instances of this monitored

3434

# resource type. For example, an individual Google Cloud SQL database is

3435

# identified by values for the labels `"database_id"` and `"zone"`.

3436

{ # A description of a label.

3437

"valueType": "A String", # The type of data that can be assigned to the label.

3438

"key": "A String", # The label key.

3439

"description": "A String", # A human-readable description for the label.

3440

},

3441

],

3442

"type": "A String", # Required. The monitored resource type. For example, the type

3443

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3444

# The maximum length of this value is 256 characters.

3445

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3446

# be used in documentation.

3447

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3448

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3449

# without any article or other determiners. For example,

3450

# `"Google Cloud SQL Database"`.

3451

},

3452

],

3453

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

3454

#

3455

# The example below shows how to configure monitored resources and metrics

3456

# for monitoring. In the example, a monitored resource and two metrics are

3457

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3458

# to both producer and consumer projects, whereas the

3459

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3460

# consumer project.

3461

#

3462

# monitored_resources:

3463

# - type: library.googleapis.com/branch

3464

# labels:

3465

# - key: /city

3466

# description: The city where the library branch is located in.

3467

# - key: /name

3468

# description: The name of the branch.

3469

# metrics:

3470

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3475

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3480

# monitoring:

3481

# producer_destinations:

3482

# - monitored_resource: library.googleapis.com/branch

3483

# metrics:

3484

# - library.googleapis.com/book/returned_count

3485

# consumer_destinations:

3486

# - monitored_resource: library.googleapis.com/branch

3487

# metrics:

3488

# - library.googleapis.com/book/returned_count

3489

# - library.googleapis.com/book/overdue_count

3490

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3491

# There can be multiple producer destinations. A monitored resouce type may

3492

# appear in multiple monitoring destinations if different aggregations are

3493

# needed for different sets of metrics associated with that monitored

3494

# resource type. A monitored resource and metric pair may only be used once

3495

# in the Monitoring configuration.

3496

{ # Configuration of a specific monitoring destination (the producer project

3497

# or the consumer project).

3498

"metrics": [ # Types of the metrics to report to this monitoring destination.

3499

# Each type must be defined in Service.metrics section.

3500

"A String",

3501

],

3502

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3503

# Service.monitored_resources section.

3504

},

3505

],

3506

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3507

# There can be multiple consumer destinations. A monitored resouce type may

3508

# appear in multiple monitoring destinations if different aggregations are

3509

# needed for different sets of metrics associated with that monitored

3510

# resource type. A monitored resource and metric pair may only be used once

3511

# in the Monitoring configuration.

3512

{ # Configuration of a specific monitoring destination (the producer project

3513

# or the consumer project).

3514

"metrics": [ # Types of the metrics to report to this monitoring destination.

3515

# Each type must be defined in Service.metrics section.

3516

"A String",

3517

],

3518

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3519

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3520

},

3521

],

3522

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3523

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3524

#

3525

# A system parameter is a special kind of parameter defined by the API

3526

# system, not by an individual API. It is typically mapped to an HTTP header

3527

# and/or a URL query parameter. This configuration specifies which methods

3528

# change the names of the system parameters.

3529

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3530

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3531

# The parameters defined here will override the default parameters

3532

# implemented by the system. If this field is missing from the service

3533

# config, default system parameters will be used. Default system parameters

3534

# and names is implementation-dependent.

3535

#

3536

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3544

#

3545

#

3546

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3551

# parameters:

3552

# - name: api_key

3553

# http_header: Api-Key1

3554

# - name: api_key

3555

# http_header: Api-Key2

3556

#

3557

# **NOTE:** All service configuration rules follow "last one wins" order.

3558

{ # Define a system parameter rule mapping system parameter definitions to

3559

# methods.

3560

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3561

# For a given method call, only one of them should be used. If multiple

3562

# names are used the behavior is implementation-dependent.

3563

# If none of the specified names are present the behavior is

3564

# parameter-dependent.

3565

{ # Define a parameter's name and location. The parameter may be passed as either

3566

# an HTTP header or a URL query parameter, and if both are passed the behavior

3567

# is implementation-dependent.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3568

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3569

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3570

# sensitive.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3571

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

3572

# insensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3573

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3574

],

3575

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3576

# methods in all APIs.

3577

#

3578

# Refer to selector for syntax details.

3579

},

3580

],

3581

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3582

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

3583

# usage.

3584

#

3585

# The metric based quota configuration works this way:

3586

# - The service configuration defines a set of metrics.

3587

# - For API calls, the quota.metric_rules maps methods to metrics with

3588

# corresponding costs.

3589

# - The quota.limits defines limits on the metrics, which will be used for

3590

# quota checks at runtime.

3591

#

3592

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

3598

# metric: library.googleapis.com/write_calls

3599

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

3605

# # except for the UpdateBook and DeleteBook methods. These two methods

3606

# # are mapped to the write_calls metric, with the UpdateBook method

3607

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

3612

# - selector: google.example.library.v1.LibraryService.UpdateBook

3613

# metric_costs:

3614

# library.googleapis.com/write_calls: 2

3615

# - selector: google.example.library.v1.LibraryService.DeleteBook

3616

# metric_costs:

3617

# library.googleapis.com/write_calls: 1

3618

#

3619

# Corresponding Metric definition:

3620

#

3621

# metrics:

3622

# - name: library.googleapis.com/read_calls

3623

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

3628

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

3633

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

3634

# for a limit type. There can be at most one limit for a duration and limit

3635

# type combination defined within a `QuotaGroup`.

3636

"displayName": "A String", # User-visible display name for this limit.

3637

# Optional. If not set, the UI will provide a default display name based on

3638

# the quota configuration. This field can be used to override the default

3639

# display name generated from the configuration.

3640

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

3641

# duration. Client application developers can override the default limit up

3642

# to this maximum. If specified, this value cannot be set to a value less

3643

# than the default limit. If not specified, it is set to the default limit.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3644

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3645

# To allow clients to apply overrides with no upper bound, set this to -1,

3646

# indicating unlimited maximum quota.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3647

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3648

# Used by group-based quotas only.

3649

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3650

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3651

# Used by group-based quotas only.

3652

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

3653

# The free tier is the number of tokens that will be subtracted from the

3654

# billed amount when billing is enabled.

3655

# This field can only be set on a limit with duration "1d", in a billable

3656

# group; it is invalid on any other limit. If this field is not set, it

3657

# defaults to 0, indicating that there is no free tier for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3658

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3659

# Used by group-based quotas only.

3660

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

3661

# Metric.unit. The supported unit kinds are determined by the quota

3662

# backend system.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3663

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3664

# Here are some examples:

3665

# * "1/min/{project}" for quota per minute per project.

3666

#

3667

# Note: the order of unit components is insignificant.

3668

# The "1" at the beginning is required to follow the metric unit syntax.

3669

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

3670

# duration. This is the number of tokens assigned when a client

3671

# application developer activates the service for his/her project.

3672

#

3673

# Specifying a value of 0 will block all requests. This can be used if you

3674

# are provisioning quota to selected consumers and blocking others.

3675

# Similarly, a value of -1 will indicate an unlimited quota. No other

3676

# negative values are allowed.

3677

#

3678

# Used by group-based quotas only.

3679

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

3680

# integer value that is the maximum number of requests allowed for the

3681

# specified unit. Currently only STANDARD is supported.

3682

"a_key": "A String",

3683

},

3684

"name": "A String", # Name of the quota limit.

3685

#

3686

# The name must be provided, and it must be unique within the service. The

3687

# name can only include alphanumeric characters as well as '-'.

3688

#

3689

# The maximum length of the limit name is 64 characters.

3690

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

3691

# the same metric will be checked together during runtime. The metric must be

3692

# defined within the service config.

3693

"description": "A String", # Optional. User-visible, extended description for this quota limit.

3694

# Should be used only when more context is needed to understand this limit

3695

# than provided by the limit's display name (see: `display_name`).

3696

},

3697

],

3698

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

3699

# or more metrics.

3700

{ # Bind API methods to metrics. Binding a method to a metric causes that

3701

# metric's configured quota behaviors to apply to the method call.

3702

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

3703

# cost applied to each metric.

3704

#

3705

# The key of the map is the metric name, and the values are the amount

3706

# increased for the metric against which the quota limits are defined.

3707

# The value must not be negative.

3708

"a_key": "A String",

3709

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3710

"selector": "A String", # Selects the methods to which this rule applies.

3711

#

3712

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3713

},

3714

],

3715

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3716

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3717

#

3718

# Example:

3719

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

3725

# - google.rpc.context.OriginContext

3726

#

3727

# The above specifies that all methods in the API request

3728

# `google.rpc.context.ProjectContext` and

3729

# `google.rpc.context.OriginContext`.

3730

#

3731

# Available context types are defined in package

3732

# `google.rpc.context`.

3733

#

3734

# This also provides mechanism to whitelist any protobuf message extension that

3735

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

3736

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

3737

# 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"

3745

# allowed_request_extensions:

3746

# - google.foo.v1.NewExtension

3747

# allowed_response_extensions:

3748

# - google.foo.v1.NewExtension

3749

#

3750

# You can also specify extension ID instead of fully qualified extension name

3751

# here.

3752

"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]

3753

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3754

# **NOTE:** All service configuration rules follow "last one wins" order.

3755

{ # A context rule provides information about the context for an individual API

3756

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3757

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3758

# side channel from client to backend.

3759

"A String",

3760

],

3761

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3762

# side channel from backend to client.

3763

"A String",

3764

],

3765

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3766

#

3767

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3768

"requested": [ # A list of full type names of requested contexts.

3769

"A String",

3770

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3771

"provided": [ # A list of full type names of provided contexts.

3772

"A String",

3773

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3774

},

3775

],

3776

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3777

"producerProjectId": "A String", # The Google project that owns this service.

3778

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3779

"rules": [ # A list of API backend rules that apply to individual API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3780

#

3781

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3782

{ # A backend rule provides configuration for an individual API element.

3783

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

3784

# operation. The default is no deadline.

3785

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

3786

# value lower than this will be rejected.

3787

"address": "A String", # The address of the API backend.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3788

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3789

# The scheme is used to determine the backend protocol and security.

3790

# The following schemes are accepted:

3791

#

3792

# 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

3799

# may cause constrasting behaviors across platforms.

3800

#

3801

# If the port is unspecified, the default is:

3802

# - 80 for schemes without TLS

3803

# - 443 for schemes with TLS

3804

#

3805

# For HTTP backends, use protocol

3806

# to specify the protocol version.

3807

"pathTranslation": "A String",

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3808

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3809

#

3810

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3811

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

3812

# This ID token will be added in the HTTP "authorization" header, and sent

3813

# to the backend.

3814

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

3815

# original "Authorization" HTTP header will be preserved. If the header is

3816

# used to carry the original token and is expected by the backend, this

3817

# field must be set to true to preserve the header.

3818

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

3819

# varies based on the request protocol and deployment environment.

3820

"protocol": "A String", # The protocol used for sending a request to the backend.

3821

# The supported values are "http/1.1" and "h2".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3822

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3823

# The default value is inferred from the scheme in the

3824

# address field:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3825

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3831

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3832

# For secure HTTP backends (https://) that support HTTP/2, set this field

3833

# to "h2" for improved performance.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3834

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3835

# Configuring this field to non-default values is only supported for secure

3836

# HTTP backends. This field will be ignored for all other backends.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3837

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3838

# See

3839

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

3840

# for more details on the supported values.

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]

3848

<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]

3849

<pre>Gets a service configuration (version) for a managed service.

3850

3851

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3852

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]

3853

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

3854

configId: string, Required. The id of the service configuration resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3855

3856

This field must be specified for the server to return all fields, including

3857

`SourceInfo`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3858

view: string, Specifies which parts of the Service Config should be returned in the

3859

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3860

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3867

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3868

{ # `Service` is the root object of Google service configuration schema. It

3869

# describes basic information about a service, such as the name and the

3870

# title, and delegates other aspects to sub-sections. Each sub-section is

3871

# either a proto message or a repeated proto message that configures a

3872

# 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]

3877

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3878

# name: calendar.googleapis.com

3879

# title: Google Calendar API

3880

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3881

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3882

# authentication:

3883

# providers:

3884

# - id: google_calendar_auth

3885

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3886

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3887

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3888

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3889

# requirements:

3890

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3891

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3892

# service controller handles features like abuse, quota, billing, logging,

3893

# monitoring, etc.

3894

"environment": "A String", # The service control environment to use. If empty, no control plane

3895

# feature (like quota and billing) will be enabled.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3896

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3897

"types": [ # A list of all proto message types included in this API service.

3898

# Types referenced directly or indirectly by the `apis` are

3899

# automatically included. Messages which are not referenced but

3900

# shall be included, such as types used by the `google.protobuf.Any` type,

3901

# should be listed here by name. Example:

3902

#

3903

# types:

3904

# - name: google.protobuf.Int32

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3905

{ # A protocol buffer message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3906

"fields": [ # The list of fields.

3907

{ # A single field of a message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3908

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3909

"name": "A String", # The field name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3910

"kind": "A String", # The field type.

3911

"jsonName": "A String", # The field JSON name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3912

"cardinality": "A String", # The field cardinality.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3913

"options": [ # The protocol buffer options.

3914

{ # A protocol buffer option, which can be attached to a message, field,

3915

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3916

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3917

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3918

# For custom options, it should be the fully-qualified name. For example,

3919

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3920

"value": { # The option's value packed in an Any message. If the value is a primitive,

3921

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3922

# should be used. If the value is an enum, it should be stored as an int32

3923

# value using the google.protobuf.Int32Value type.

3924

"a_key": "", # Properties of the object. Contains field @type with type URL.

3925

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3926

},

3927

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3928

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3929

"packed": True or False, # Whether to use alternative packed wire representation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3930

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3931

# types. The first type has index 1; zero means the type is not in the list.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3932

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3933

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3934

},

3935

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3936

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3937

"A String",

3938

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3939

"name": "A String", # The fully qualified message name.

3940

"options": [ # The protocol buffer options.

3941

{ # A protocol buffer option, which can be attached to a message, field,

3942

# enumeration, etc.

3943

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3944

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3945

# For custom options, it should be the fully-qualified name. For example,

3946

# `"google.api.http"`.

3947

"value": { # The option's value packed in an Any message. If the value is a primitive,

3948

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3949

# should be used. If the value is an enum, it should be stored as an int32

3950

# value using the google.protobuf.Int32Value type.

3951

"a_key": "", # Properties of the object. Contains field @type with type URL.

3952

},

3953

},

3954

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3955

"syntax": "A String", # The source syntax.

3956

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3957

# protobuf element, like the file in which it is defined.

3958

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3959

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3960

},

3961

},

3962

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3963

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

3964

"sourceFiles": [ # All files used during config generation.

3965

{

3966

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

3971

# service, such as `calendar.googleapis.com`. The service name

3972

# typically goes through DNS verification to make sure the owner

3973

# of the service also owns the DNS name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3974

"title": "A String", # The product title for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3975

"logs": [ # Defines the logs used by this service.

3976

{ # A description of a log type. Example in YAML format:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3977

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3978

# - name: library.googleapis.com/activity_history

3979

# description: The history of borrowing and returning library items.

3980

# display_name: Activity

3981

# labels:

3982

# - key: /customer_id

3983

# description: Identifier of a library customer

3984

"labels": [ # The set of labels that are available to describe a specific log entry.

3985

# Runtime requests that contain labels not specified here are

3986

# considered invalid.

3987

{ # A description of a label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3988

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3989

"key": "A String", # The label key.

3990

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3991

},

3992

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3993

"description": "A String", # A human-readable description of this log. This information appears in

3994

# the documentation and can contain details.

3995

"displayName": "A String", # The human-readable name for this log. This information appears on

3996

# the user interface and should be concise.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

3997

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3998

# include the following characters: upper- and lower-case alphanumeric

3999

# characters [A-Za-z0-9], and punctuation characters including

4000

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4001

},

4002

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4003

"metrics": [ # Defines the metrics used by this service.

4004

{ # Defines a metric type and its schema. Once a metric descriptor is created,

4005

# deleting or altering it stops data collection and makes the metric type's

4006

# existing data unusable.

4007

"type": "A String", # The metric type, including its DNS name prefix. The type is not

4008

# URL-encoded. All user-defined metric types have the DNS name

4009

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

4010

# use a natural hierarchical grouping. For example:

4011

#

4012

# "custom.googleapis.com/invoice/paid/amount"

4013

# "external.googleapis.com/prometheus/up"

4014

# "appengine.googleapis.com/http/server/response_latencies"

4015

"labels": [ # The set of labels that can be used to describe a specific

4016

# instance of this metric type. For example, the

4017

# `appengine.googleapis.com/http/server/response_latencies` metric

4018

# type has a label for the HTTP response code, `response_code`, so

4019

# you can look at latencies for successful responses or just

4020

# for responses that failed.

4021

{ # A description of a label.

4022

"valueType": "A String", # The type of data that can be assigned to the label.

4023

"key": "A String", # The label key.

4024

"description": "A String", # A human-readable description for the label.

4025

},

4026

],

4027

"description": "A String", # A detailed description of the metric, which can be used in documentation.

4028

"monitoredResourceTypes": [ # Read-only. If present, then a time

4029

# series, which is identified partially by

4030

# a metric type and a MonitoredResourceDescriptor, that is associated

4031

# with this metric type can only be associated with one of the monitored

4032

# resource types listed here.

4033

"A String",

4034

],

4035

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4036

# Use sentence case without an ending period, for example "Request count".

4037

# This field is optional but it is recommended to be set for any metrics

4038

# associated with user-visible concepts, such as Quota.

4039

"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.

4040

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

4041

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

4042

# age are guaranteed to be ingested and available to be read, excluding

4043

# data loss due to errors.

4044

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

4045

# periodically, consecutive data points are stored at this time interval,

4046

# excluding data loss due to errors. Metrics with a higher granularity have

4047

# a smaller sampling period.

4048

},

4049

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

4050

# Some combinations of `metric_kind` and `value_type` might not be supported.

4051

"unit": "A String", # The units in which the metric value is reported. It is only applicable

4052

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

4053

# defines the representation of the stored metric values.

4054

#

4055

# Different systems may scale the values to be more easily displayed (so a

4056

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

4057

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

4058

# `KBy`, then the value of the metric is always in thousands of bytes, no

4059

# matter how it may be displayed..

4060

#

4061

# If you want a custom metric to record the exact number of CPU-seconds used

4062

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

4063

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

4064

# CPU-seconds, then the value is written as `12005`.

4065

#

4066

# Alternatively, if you want a custom metric to record data in a more

4067

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

4068

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

4069

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

4070

#

4071

# The supported units are a subset of [The Unified Code for Units of

4072

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4073

#

4074

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

4092

# * `Y` yotta (10^24)

4093

#

4094

# * `m` milli (10^-3)

4095

# * `u` micro (10^-6)

4096

# * `n` nano (10^-9)

4097

# * `p` pico (10^-12)

4098

# * `f` femto (10^-15)

4099

# * `a` atto (10^-18)

4100

# * `z` zepto (10^-21)

4101

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

#

# **Grammar**

#

# The grammar also includes these connectors:

4112

#

4113

# * `/` division or ratio (as an infix operator). For examples,

4114

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

4115

# have `/s` in a metric `unit`; rates should always be computed at

4116

# query time from the underlying cumulative or delta value).

4117

# * `.` multiplication or composition (as an infix operator). For

4118

# examples, `GBy.d` or `k{watt}.h`.

4119

#

4120

# The grammar for a unit is as follows:

4121

#

4122

# Expression = Component { "." Component } { "/" Component } ;

4123

#

4124

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

4134

# is used alone, then the unit is equivalent to `1`. For examples,

4135

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

4136

# * `NAME` is a sequence of non-blank printable ASCII characters not

4137

# containing `{` or `}`.

4138

# * `1` represents a unitary [dimensionless

4139

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

4140

# as in `1/s`. It is typically used when none of the basic units are

4141

# appropriate. For example, "new users per day" can be represented as

4142

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

4143

# users). Alternatively, "thousands of page views per day" would be

4144

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

4145

# value of `5.3` would mean "5300 page views per day").

4146

# * `%` represents dimensionless value of 1/100, and annotates values giving

4147

# a percentage (so the metric values are typically in the range of 0..100,

4148

# and a metric value `3` means "3 percent").

4149

# * `10^2.%` indicates a metric contains a ratio, typically in the range

4150

# 0..1, that will be multiplied by 100 and displayed as a percentage

4151

# (so a metric value `0.03` means "3 percent").

4152

"launchStage": "A String", # Optional. The launch stage of the metric definition.

4153

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

4154

# Some combinations of `metric_kind` and `value_type` might not be supported.

4155

"name": "A String", # The resource name of the metric descriptor.

4156

},

4157

],

4158

"enums": [ # A list of all enum types included in this API service. Enums

4159

# referenced directly or indirectly by the `apis` are automatically

4160

# included. Enums which are not referenced but shall be included

4161

# should be listed here by name. Example:

4162

#

4163

# enums:

4164

# - name: google.someapi.v1.SomeEnum

4165

{ # Enum type definition.

4166

"options": [ # Protocol buffer options.

4167

{ # A protocol buffer option, which can be attached to a message, field,

4168

# enumeration, etc.

4169

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4170

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4171

# For custom options, it should be the fully-qualified name. For example,

4172

# `"google.api.http"`.

4173

"value": { # The option's value packed in an Any message. If the value is a primitive,

4174

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4175

# should be used. If the value is an enum, it should be stored as an int32

4176

# value using the google.protobuf.Int32Value type.

4177

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

4182

"syntax": "A String", # The source syntax.

4183

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4184

# protobuf element, like the file in which it is defined.

4185

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4186

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4187

},

4188

"enumvalue": [ # Enum value definitions.

4189

{ # Enum value definition.

4190

"name": "A String", # Enum value name.

4191

"number": 42, # Enum value number.

4192

"options": [ # Protocol buffer options.

4193

{ # A protocol buffer option, which can be attached to a message, field,

4194

# enumeration, etc.

4195

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4196

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4197

# For custom options, it should be the fully-qualified name. For example,

4198

# `"google.api.http"`.

4199

"value": { # The option's value packed in an Any message. If the value is a primitive,

4200

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4201

# should be used. If the value is an enum, it should be stored as an int32

4202

# value using the google.protobuf.Int32Value type.

4203

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

},

],

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4212

#

4213

# Example for an API targeted for external use:

4214

#

4215

# name: calendar.googleapis.com

4216

# authentication:

4217

# providers:

4218

# - id: google_calendar_auth

4219

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4220

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

4225

"rules": [ # A list of authentication rules that apply to individual API methods.

4226

#

4227

# **NOTE:** All service configuration rules follow "last one wins" order.

4228

{ # Authentication rules for the service.

4229

#

4230

# By default, if a method has any authentication requirements, every request

4231

# must include a valid credential matching one of the requirements.

4232

# It's an error to include more than one kind of credential in a single

4233

# request.

4234

#

4235

# If a method doesn't have any auth requirements, request credentials will be

4236

# ignored.

4237

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4238

# there are scopes defined for "Read-only access to Google Calendar" and

4239

# "Access to Cloud Platform". Users can consent to a scope for an application,

4240

# giving it permission to access that data on their behalf.

4241

#

4242

# OAuth scope specifications should be fairly coarse grained; a user will need

4243

# to see and understand the text description of what your scope means.

4244

#

4245

# In most cases: use one or at most two OAuth scopes for an entire family of

4246

# products. If your product has multiple APIs, you should probably be sharing

4247

# the OAuth scope across all of those APIs.

4248

#

4249

# When you need finer grained OAuth consent screens: talk with your product

4250

# management about how developers will use them in practice.

4251

#

4252

# Please note that even though each of the canonical scopes is enough for a

4253

# request to be accepted and passed to the backend, a request can still fail

4254

# due to the backend requiring additional scopes or permissions.

4255

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4256

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4261

# https://www.googleapis.com/auth/calendar.read

4262

},

4263

"requirements": [ # Requirements for additional authentication providers.

4264

{ # User-defined authentication requirements, including support for

4265

# [JSON Web Token

4266

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4267

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

4268

# implemented and accepted in all the runtime components.

4269

#

4270

# The list of JWT

4271

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4272

# that are allowed to access. A JWT containing any of these audiences will

4273

# be accepted. When this setting is absent, only JWTs with audience

4274

# "https://Service_name/API_name"

4275

# will be accepted. For example, if no audiences are in the setting,

4276

# LibraryService API will only accept JWTs with the following audience

4277

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4282

# bookstore_web.apps.googleusercontent.com

4283

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

4288

},

4289

],

4290

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

4291

"selector": "A String", # Selects the methods to which this rule applies.

4292

#

4293

# Refer to selector for syntax details.

4294

},

4295

],

4296

"providers": [ # Defines a set of authentication providers that a service supports.

4297

{ # Configuration for an authentication provider, including support for

4298

# [JSON Web Token

4299

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4300

"audiences": "A String", # The list of JWT

4301

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4302

# that are allowed to access. A JWT containing any of these audiences will

4303

# be accepted. When this setting is absent, JWTs with audiences:

4304

# - "https://[service.name]/[google.protobuf.Api.name]"

4305

# - "https://[service.name]/"

4306

# will be accepted.

4307

# For example, if no audiences are in the setting, LibraryService API will

4308

# accept JWTs with the following audiences:

4309

# -

4310

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

4311

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4316

# bookstore_web.apps.googleusercontent.com

4317

"jwtLocations": [ # Defines the locations to extract the JWT.

4318

#

4319

# JWT locations can be either from HTTP headers or URL query parameters.

4320

# The rule is that the first match wins. The checking order is: checking

4321

# all headers first, then URL query parameters.

4322

#

4323

# If not specified, default to use following 3 locations:

4324

# 1) Authorization: Bearer

4325

# 2) x-goog-iap-jwt-assertion

4326

# 3) access_token query parameter

4327

#

4328

# Default locations can be specified as followings:

4329

# jwt_locations:

4330

# - header: Authorization

4331

# value_prefix: "Bearer "

4332

# - header: x-goog-iap-jwt-assertion

4333

# - query: access_token

4334

{ # Specifies a location to extract JWT from an API request.

4335

"query": "A String", # Specifies URL query parameter name to extract JWT token.

4336

"header": "A String", # Specifies HTTP header name to extract JWT token.

4337

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

4338

# Only applies to "in" header type. Must be empty for "in" query type.

4339

# If not empty, the header value has to match (case sensitive) this prefix.

4340

# If not matched, JWT will not be extracted. If matched, JWT will be

4341

# extracted after the prefix is removed.

4342

#

4343

# For example, for "Authorization: Bearer {JWT}",

4344

# value_prefix="Bearer " with a space at the end.

4345

},

4346

],

4347

"issuer": "A String", # Identifies the principal that issued the JWT. See

4348

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4349

# Usually a URL or an email address.

4350

#

4351

# Example: https://securetoken.google.com

4352

# Example: 1234567-compute@developer.gserviceaccount.com

4353

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4354

# `AuthRequirement.provider_id`.

4355

#

4356

# Example: "bookstore_auth".

4357

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4358

# [OpenID

4359

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4360

# Optional if the key set document:

4361

# - can be retrieved from

4362

# [OpenID

4363

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

4364

# the issuer.

4365

# - can be inferred from the email domain of the issuer (e.g. a Google

4366

# service account).

4367

#

4368

# Example: https://www.googleapis.com/oauth2/v1/certs

4369

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

4370

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

},

],

},

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4375

#

4376

# Example:

4377

# <pre><code>documentation:

4378

# summary: >

4379

# The Google Calendar API gives access

4380

# to most calendar features.

4381

# pages:

4382

# - name: Overview

4383

# content: &#40;== include google/foo/overview.md ==&#41;

4384

# - name: Tutorial

4385

# content: &#40;== include google/foo/tutorial.md ==&#41;

4386

# subpages;

4387

# - name: Java

4388

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

4389

# rules:

4390

# - selector: google.calendar.Calendar.Get

4391

# description: >

4392

# ...

4393

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

4398

# standard markdown features, definition lists, tables and fenced

4399

# code blocks are supported. Section headers can be provided and are

4400

# interpreted relative to the section nesting of the context where

4401

# a documentation fragment is embedded.

4402

#

4403

# Documentation from the IDL is merged with documentation defined

4404

# via the config at normalization time, where documentation provided

4405

# by config rules overrides IDL provided.

4406

#

4407

# A number of constructs specific to the API platform are supported

4408

# in documentation text.

4409

#

4410

# In order to reference a proto element, the following

4411

# notation can be used:

4412

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

4413

# To override the display text used for the link, this can be used:

4414

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

4415

# Text can be excluded from doc using the following notation:

4416

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

4417

#

4418

# A few directives are available in documentation. Note that

4419

# directives must appear on a single line to be properly

4420

# identified. The `include` directive includes a markdown file from

4421

# an external source:

4422

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

4423

# The `resource_for` directive marks a message to be the resource of

4424

# a collection in REST view. If it is not specified, tools attempt

4425

# to infer the resource from the operations in a collection:

4426

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

4427

# The directive `suppress_warning` does not directly affect documentation

4428

# and is documented together with service config validation.

4429

"documentationRootUrl": "A String", # The URL to the root of documentation.

4430

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

4431

# from the yaml file) is not suitable. This can be seen in any fully

4432

# specified service urls as well as sections that show a base that other

4433

# urls are relative to.

4434

"rules": [ # A list of documentation rules that apply to individual API elements.

4435

#

4436

# **NOTE:** All service configuration rules follow "last one wins" order.

4437

{ # A documentation rule provides information about individual API elements.

4438

"description": "A String", # Description of the selected API(s).

4439

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

4440

# an element is marked as `deprecated`.

4441

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

4442

# qualified name of the element which may end in "*", indicating a wildcard.

4443

# Wildcards are only allowed at the end and for a whole component of the

4444

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

4445

# wildcard will match one or more components. To specify a default for all

4446

# applicable elements, the whole pattern "*" is used.

4447

},

4448

],

4449

"pages": [ # The top level pages for the documentation set.

4450

{ # Represents a documentation page. A page can contain subpages to represent

4451

# nested documentation set structure.

4452

"name": "A String", # The name of the page. It will be used as an identity of the page to

4453

# generate URI of the page, text of the link to this page in navigation,

4454

# etc. The full page name (start from the root page name to this page

4455

# concatenated with `.`) can be used as reference to the page in your

4456

# documentation. For example:

4457

# <pre><code>pages:

4458

# - name: Tutorial

4459

# content: &#40;== include tutorial.md ==&#41;

4460

# subpages:

4461

# - name: Java

4462

# content: &#40;== include tutorial_java.md ==&#41;

4463

# </code></pre>

4464

# You can reference `Java` page using Markdown reference link syntax:

4465

# `Java`.

4466

"subpages": [ # Subpages of this page. The order of subpages specified here will be

4467

# honored in the generated docset.

4468

# Object with schema name: Page

4469

],

4470

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

4471

# ==&#41;</code> to include content from a Markdown file.

4472

},

4473

],

4474

"summary": "A String", # A short summary of what the service does. Can only be provided by

4475

# plain text.

4476

"overview": "A String", # Declares a single overview page. For example:

4477

# <pre><code>documentation:

4478

# summary: ...

4479

# overview: &#40;== include overview.md ==&#41;

4480

# </code></pre>

4481

# This is a shortcut for the following declaration (using pages style):

4482

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

4487

# </code></pre>

4488

# Note: you cannot specify both `overview` field and `pages` field.

4489

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4490

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4491

# of the google.protobuf.Api needs to be provided by the configuration

4492

# author, as the remaining fields will be derived from the IDL during the

4493

# normalization process. It is an error to specify an API interface here

4494

# which cannot be resolved against the associated IDL files.

4495

{ # Api is a light-weight descriptor for an API Interface.

4496

#

4497

# Interfaces are also described as "protocol buffer services" in some contexts,

4498

# such as by the "service" keyword in a .proto file, but they are different

4499

# from API Services, which represent a concrete implementation of an interface

4500

# as opposed to simply a description of methods and bindings. They are also

4501

# sometimes simply referred to as "APIs" in other contexts, such as the name of

4502

# this message itself. See https://cloud.google.com/apis/design/glossary for

4503

# detailed terminology.

4504

"options": [ # Any metadata attached to the interface.

4505

{ # A protocol buffer option, which can be attached to a message, field,

4506

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4507

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4508

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4509

# For custom options, it should be the fully-qualified name. For example,

4510

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4511

"value": { # The option's value packed in an Any message. If the value is a primitive,

4512

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4513

# should be used. If the value is an enum, it should be stored as an int32

4514

# value using the google.protobuf.Int32Value type.

4515

"a_key": "", # Properties of the object. Contains field @type with type URL.

4516

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4517

},

4518

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4519

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4520

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4521

# message.

4522

# protobuf element, like the file in which it is defined.

4523

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4524

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4525

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4526

"mixins": [ # Included interfaces. See Mixin.

4527

{ # Declares an API Interface to be included in this interface. The including

4528

# interface must redeclare all the methods from the included interface, but

4529

# documentation and options are inherited as follows:

4530

#

4531

# - If after comment and whitespace stripping, the documentation

4532

# string of the redeclared method is empty, it will be inherited

4533

# from the original method.

4534

#

4535

# - Each annotation belonging to the service config (http,

4536

# visibility) which is not set in the redeclared method will be

4537

# inherited.

4538

#

4539

# - If an http annotation is inherited, the path pattern will be

4540

# modified as follows. Any version prefix will be replaced by the

4541

# version of the including interface plus the root path if

4542

# specified.

4543

#

4544

# Example of a simple mixin:

4545

#

4546

# package google.acl.v1;

4547

# service AccessControl {

4548

# // Get the underlying ACL object.

4549

# rpc GetAcl(GetAclRequest) returns (Acl) {

4550

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4555

# service Storage {

4556

# // rpc GetAcl(GetAclRequest) returns (Acl);

4557

#

4558

# // Get a data record.

4559

# rpc GetData(GetDataRequest) returns (Data) {

4560

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4565

#

4566

# apis:

4567

# - name: google.storage.v2.Storage

4568

# mixins:

4569

# - name: google.acl.v1.AccessControl

4570

#

4571

# The mixin construct implies that all methods in `AccessControl` are

4572

# also declared with same name and request/response types in

4573

# `Storage`. A documentation generator or annotation processor will

4574

# see the effective `Storage.GetAcl` method after inherting

4575

# documentation and annotations as follows:

4576

#

4577

# service Storage {

4578

# // Get the underlying ACL object.

4579

# rpc GetAcl(GetAclRequest) returns (Acl) {

4580

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4586

#

4587

# If the `root` field in the mixin is specified, it should be a

4588

# relative path under which inherited HTTP paths are placed. Example:

4589

#

4590

# apis:

4591

# - name: google.storage.v2.Storage

4592

# mixins:

4593

# - name: google.acl.v1.AccessControl

4594

# root: acls

4595

#

4596

# This implies the following inherited HTTP annotation:

4597

#

4598

# service Storage {

4599

# // Get the underlying ACL object.

4600

# rpc GetAcl(GetAclRequest) returns (Acl) {

4601

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"name": "A String", # The fully qualified name of the interface which is included.

4606

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4607

# are rooted.

4608

},

4609

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4610

"version": "A String", # A version string for this interface. If specified, must have the form

4611

# `major-version.minor-version`, as in `1.10`. If the minor version is

4612

# omitted, it defaults to zero. If the entire version field is empty, the

4613

# major version is derived from the package name, as outlined below. If the

4614

# field is not empty, the version in the package name will be verified to be

4615

# consistent with what is provided here.

4616

#

4617

# The versioning schema uses [semantic

4618

# versioning](http://semver.org) where the major version number

4619

# indicates a breaking change and the minor version an additive,

4620

# non-breaking change. Both version numbers are signals to users

4621

# what to expect from different versions, and should be carefully

4622

# chosen based on the product plan.

4623

#

4624

# The major version is also reflected in the package name of the

4625

# interface, which must end in `v<major-version>`, as in

4626

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4627

# be omitted. Zero major versions must only be used for

4628

# experimental, non-GA interfaces.

4629

"methods": [ # The methods of this interface, in unspecified order.

4630

{ # Method represents a method of an API interface.

4631

"requestTypeUrl": "A String", # A URL of the input message type.

4632

"name": "A String", # The simple name of this method.

4633

"responseStreaming": True or False, # If true, the response is streamed.

4634

"requestStreaming": True or False, # If true, the request is streamed.

4635

"options": [ # Any metadata attached to the method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4636

{ # A protocol buffer option, which can be attached to a message, field,

4637

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4638

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4639

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4640

# For custom options, it should be the fully-qualified name. For example,

4641

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4642

"value": { # The option's value packed in an Any message. If the value is a primitive,

4643

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4644

# should be used. If the value is an enum, it should be stored as an int32

4645

# value using the google.protobuf.Int32Value type.

4646

"a_key": "", # Properties of the object. Contains field @type with type URL.

4647

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4648

},

4649

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4650

"syntax": "A String", # The source syntax of this method.

4651

"responseTypeUrl": "A String", # The URL of the output message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4652

},

4653

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4654

"name": "A String", # The fully qualified name of this interface, including package name

4655

# followed by the interface's simple name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4656

},

4657

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4658

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4659

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

4667

# - google.foo.v1.AnotherError

4668

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

4669

"A String",

4670

],

4671

"rules": [ # The list of custom error rules that apply to individual API messages.

4672

#

4673

# **NOTE:** All service configuration rules follow "last one wins" order.

4674

{ # A custom error rule.

4675

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4676

# objects of this type will be filtered when they appear in error payload.

4677

"selector": "A String", # Selects messages to which this rule applies.

4678

#

4679

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4680

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4681

],

4682

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

4683

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4684

# by the client for tracking purpose. Must be no longer than 63 characters

4685

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

4686

# empty, the server may choose to generate one instead.

4687

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4688

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4689

# service. Each requirement is of the form <service.name>/<requirement-id>;

4690

# for example 'serviceusage.googleapis.com/billing-enabled'.

4691

"A String",

4692

],

4693

"rules": [ # A list of usage rules that apply to individual API methods.

4694

#

4695

# **NOTE:** All service configuration rules follow "last one wins" order.

4696

{ # Usage configuration rules for the service.

4697

#

4698

# NOTE: Under development.

4699

#

4700

#

4701

# Use this rule to configure unregistered calls for the service. Unregistered

4702

# calls are calls that do not contain consumer project identity.

4703

# (Example: calls that do not contain an API key).

4704

# By default, API methods do not allow unregistered calls, and each method call

4705

# must be identified by a consumer project identity. Use this rule to

4706

# allow/disallow unregistered calls.

4707

#

4708

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4714

#

4715

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4720

# allow_unregistered_calls: true

4721

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4722

# methods in all APIs.

4723

#

4724

# Refer to selector for syntax details.

4725

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

4726

# that don't identify any user or application.

4727

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

4728

# plane features, such as quota and billing, will not be available.

4729

# This flag is used by Google Cloud Endpoints to bypass checks for internal

4730

# methods, such as service health check methods.

4731

},

4732

],

4733

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4734

# service producer.

4735

#

4736

# Google Service Management currently only supports

4737

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

4738

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

4739

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

4740

# documented in https://cloud.google.com/pubsub/docs/overview.

4741

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

4742

#

4743

#

4744

# Use this field to configure per-product per-project service identity.

4745

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

4750

# display_name: "Cloud XXX Service Agent"

4751

# description: "Used as the identity of Cloud XXX to access resources"

4752

"displayName": "A String", # Optional. A user-specified name for the service account.

4753

# Must be less than or equal to 100 UTF-8 bytes.

4754

"description": "A String", # Optional. A user-specified opaque description of the service account.

4755

# Must be less than or equal to 256 UTF-8 bytes.

4756

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

4757

#

4758

# An example name would be:

4759

# `projects/123456789`

4760

},

4761

},

4762

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4763

# with the same name as the service is automatically generated to service all

4764

# defined APIs.

4765

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4766

# A service may expose any number of endpoints, and all endpoints share the

4767

# same service configuration, such as quota configuration and monitoring

4768

# configuration.

4769

#

4770

# Example service configuration:

4771

#

4772

# name: library-example.googleapis.com

4773

# endpoints:

4774

# # Below entry makes 'google.example.library.v1.Library'

4775

# # API be served from endpoint address library-example.googleapis.com.

4776

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4777

# # it to decide whether the subsequent cross-origin request is

4778

# # allowed to proceed.

4779

# - name: library-example.googleapis.com

4780

# allow_cors: true

4781

"name": "A String", # The canonical name of this endpoint.

4782

"target": "A String", # The specification of an Internet routable address of API frontend that will

4783

# handle requests to this [API

4784

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

4785

# either a valid IPv4 address or a fully-qualified domain name. For example,

4786

# "8.8.8.8" or "myservice.appspot.com".

4787

"allowCors": True or False, # Allowing

4788

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4789

# cross-domain traffic, would allow the backends served from this endpoint to

4790

# receive and respond to HTTP OPTIONS requests. The response will be used by

4791

# the browser to determine whether the subsequent cross-origin request is

4792

# allowed to proceed.

4793

"features": [ # The list of features enabled on this endpoint.

4794

"A String",

4795

],

4796

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4797

# please specify multiple google.api.Endpoint for each of the intended

4798

# aliases.

4799

#

4800

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"configVersion": 42, # The semantic version of the service configuration. The config version

4806

# affects the interpretation of the service configuration. For example,

4807

# certain features are enabled by default for certain config versions.

4808

#

4809

# The latest config version is `3`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4810

"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]

4811

# HttpRule, each specifying the mapping of an RPC method

4812

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4813

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4814

#

4815

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4816

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4817

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4818

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

4819

# more HTTP REST endpoints. It allows developers to build a single API service

4820

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

4821

# APIs](https://github.com/googleapis/googleapis),

4822

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

4823

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

4824

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

4825

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4826

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4827

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

4828

# how different portions of the gRPC request message are mapped to the URL

4829

# path, URL query parameters, and HTTP request body. It also controls how the

4830

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

4831

# typically specified as an `google.api.http` annotation on the gRPC method.

4832

#

4833

# Each mapping specifies a URL path template and an HTTP method. The path

4834

# template may refer to one or more fields in the gRPC request message, as long

4835

# as each field is a non-repeated field with a primitive (non-message) type.

4836

# The path template controls how fields of the request message are mapped to

4837

# the URL path.

4838

#

4839

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4840

#

4841

# service Messaging {

4842

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4843

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4844

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4845

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4846

# }

4847

# }

4848

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4849

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4850

# }

4851

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4852

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4853

# }

4854

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4855

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4856

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4857

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4858

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4859

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4860

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4861

# Any fields in the request message which are not bound by the path template

4862

# automatically become HTTP query parameters if there is no HTTP request body.

4863

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4864

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4865

# service Messaging {

4866

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4867

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4868

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4869

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4870

# }

4871

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4872

# message GetMessageRequest {

4873

# message SubMessage {

4874

# string subfield = 1;

4875

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4876

# string message_id = 1; // Mapped to URL path.

4877

# int64 revision = 2; // Mapped to URL query parameter `revision`.

4878

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4879

# }

4880

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4881

# This enables a HTTP JSON to RPC mapping as below:

4882

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4883

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4884

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4885

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4886

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

4887

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4888

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4889

# Note that fields which are mapped to URL query parameters must have a

4890

# primitive type or a repeated primitive type or a non-repeated message type.

4891

# 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]

4892

# 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]

4893

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4894

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4895

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4896

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4897

# specifies the mapping. Consider a REST update method on the

4898

# message resource collection:

4899

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4900

# service Messaging {

4901

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4902

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4903

# patch: "/v1/messages/{message_id}"

4904

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

4909

# string message_id = 1; // mapped to the URL

4910

# Message message = 2; // mapped to the body

4911

# }

4912

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4913

# The following HTTP JSON to RPC mapping is enabled, where the

4914

# representation of the JSON in the request body is determined by

4915

# protos JSON encoding:

4916

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4917

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4918

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4919

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4920

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4921

#

4922

# The special name `*` can be used in the body mapping to define that

4923

# every field not bound by the path template should be mapped to the

4924

# request body. This enables the following alternative definition of

4925

# the update method:

4926

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4927

# service Messaging {

4928

# rpc UpdateMessage(Message) returns (Message) {

4929

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4930

# patch: "/v1/messages/{message_id}"

4931

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

4937

# string text = 2;

4938

# }

4939

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4940

#

4941

# The following HTTP JSON to RPC mapping is enabled:

4942

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4943

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4944

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4945

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4946

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4947

#

4948

# Note that when using `*` in the body mapping, it is not possible to

4949

# 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]

4950

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4951

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4952

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4953

#

4954

# It is possible to define multiple HTTP methods for one RPC by using

4955

# the `additional_bindings` option. Example:

4956

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4957

# service Messaging {

4958

# rpc GetMessage(GetMessageRequest) returns (Message) {

4959

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4960

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4961

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4962

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4963

# }

4964

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4965

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4966

# }

4967

# message GetMessageRequest {

4968

# string message_id = 1;

4969

# string user_id = 2;

4970

# }

4971

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4972

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4973

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4974

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4975

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4976

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4977

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

4978

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4979

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4980

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4981

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4982

# 1. Leaf request fields (recursive expansion nested messages in the request

4983

# message) are classified into three categories:

4984

# - Fields referred by the path template. They are passed via the URL path.

4985

# - Fields referred by the HttpRule.body. They are passed via the HTTP

4986

# request body.

4987

# - All other fields are passed via the URL query parameters, and the

4988

# parameter name is the field path in the request message. A repeated

4989

# field can be represented as multiple query parameters under the same

4990

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4991

# 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]

4992

# are passed via URL path and HTTP request body.

4993

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

4994

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4995

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4996

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4997

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4998

# Template = "/" Segments [ Verb ] ;

4999

# Segments = Segment { "/" Segment } ;

5000

# Segment = "*" | "**" | LITERAL | Variable ;

5001

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5002

# FieldPath = IDENT { "." IDENT } ;

5003

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5004

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5005

# The syntax `*` matches a single URL path segment. The syntax `**` matches

5006

# zero or more URL path segments, which must be the last part of the URL path

5007

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5008

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5009

# The syntax `Variable` matches part of the URL path as specified by its

5010

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5011

# matches a single path segment, its template may be omitted, e.g. `{var}`

5012

# is equivalent to `{var=*}`.

5013

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5014

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

5015

# contains any reserved character, such characters should be percent-encoded

5016

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5017

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5018

# If a variable contains exactly one path segment, such as `"{var}"` or

5019

# `"{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]

5020

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

5021

# server side does the reverse decoding. Such variables show up in the

5022

# [Discovery

5023

# Document](https://developers.google.com/discovery/v1/reference/apis) as

5024

# `{var}`.

5025

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5026

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

5027

# 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]

5028

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5029

# 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]

5030

# unchanged. Such variables show up in the

5031

# [Discovery

5032

# Document](https://developers.google.com/discovery/v1/reference/apis) as

5033

# `{+var}`.

5034

#

5035

# ## Using gRPC API Service Configuration

5036

#

5037

# gRPC API Service Configuration (service config) is a configuration language

5038

# for configuring a gRPC service to become a user-facing product. The

5039

# service config is simply the YAML representation of the `google.api.Service`

5040

# proto message.

5041

#

5042

# As an alternative to annotating your proto file, you can configure gRPC

5043

# transcoding in your service config YAML files. You do this by specifying a

5044

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

5045

# effect as the proto annotation. This can be particularly useful if you

5046

# have a proto that is reused in multiple services. Note that any transcoding

5047

# specified in the service config will override any matching transcoding

5048

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

5055

# - selector: example.v1.Messaging.GetMessage

5056

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

5061

# proto to JSON conversion must follow the [proto3

5062

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

5063

#

5064

# While the single segment variable follows the semantics of

5065

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

5066

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

5067

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

5068

# does not expand special characters like `?` and `#`, which would lead

5069

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

5070

# for multi segment variables.

5071

#

5072

# The path variables **must not** refer to any repeated or mapped field,

5073

# because client libraries are not capable of handling such variable expansion.

5074

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5075

# The path variables **must not** capture the leading "/" character. The reason

5076

# 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]

5077

# character. For consistency, all path variables must share the same behavior.

5078

#

5079

# Repeated message fields must not be mapped to URL query parameters, because

5080

# no client library can support such complicated mapping.

5081

#

5082

# If an API needs to use a JSON array for request or response body, it can map

5083

# the request or response body to a repeated field. However, some gRPC

5084

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5085

"selector": "A String", # Selects a method to which this rule applies.

5086

#

5087

# Refer to selector for syntax details.

5088

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

5089

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

5090

# included in the `pattern` field, such as HEAD, or "*" to leave the

5091

# HTTP method unspecified for this rule. The wild-card rule is useful

5092

# for services that provide content to Web (HTML) clients.

5093

"path": "A String", # The path matched by this custom verb.

5094

"kind": "A String", # The name of this custom HTTP verb.

5095

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5096

"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]

5097

# response body. When omitted, the entire response message will be used

5098

# as the HTTP response body.

5099

#

5100

# NOTE: The referred field must be present at the top-level of the response

5101

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5102

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

5103

# half-duplex streaming method.

5104

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

5105

# not contain an `additional_bindings` field themselves (that is,

5106

# the nesting may only be one level deep).

5107

# Object with schema name: HttpRule

5108

],

5109

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

5110

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

5111

# resources.

5112

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5113

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

5114

# body, or `*` for mapping all request fields not captured by the path

5115

# pattern to the HTTP body, or omitted for not having any HTTP request body.

5116

#

5117

# NOTE: the referred field must be present at the top-level of the request

5118

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5119

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

5120

},

5121

],

5122

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

5123

# cases of single segment matches in reserved expansion, where "%2F" will be

5124

# left encoded.

5125

#

5126

# The default behavior is to not decode RFC 6570 reserved characters in multi

5127

# segment matches.

5128

},

5129

"billing": { # Billing related configuration of the service. # Billing configuration.

5130

#

5131

# The following example shows how to configure monitored resources and metrics

5132

# for billing, `consumer_destinations` is the only supported destination and

5133

# the monitored resources need at least one label key

5134

# `cloud.googleapis.com/location` to indicate the location of the billing

5135

# usage, using different monitored resources between monitoring and billing is

5136

# recommended so they can be evolved independently:

5137

#

5138

#

5139

# monitored_resources:

5140

# - type: library.googleapis.com/billing_branch

5141

# labels:

5142

# - key: cloud.googleapis.com/location

5143

# description: |

5144

# Predefined label to support billing location restriction.

5145

# - key: city

5146

# description: |

5147

# Custom label to define the city where the library branch is located

5148

# in.

5149

# - key: name

5150

# description: Custom label to define the name of the library branch.

5151

# metrics:

5152

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

5158

# - monitored_resource: library.googleapis.com/billing_branch

5159

# metrics:

5160

# - library.googleapis.com/book/borrowed_count

5161

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

5162

# There can be multiple consumer destinations per service, each one must have

5163

# a different monitored resource type. A metric can be used in at most

5164

# one consumer destination.

5165

{ # Configuration of a specific billing destination (Currently only support

5166

# bill against consumer project).

5167

"metrics": [ # Names of the metrics to report to this billing destination.

5168

# Each name must be defined in Service.metrics section.

5169

"A String",

5170

],

5171

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5172

# Service.monitored_resources section.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

5177

# It serves similar purpose as [google.api.Service.types], except that

5178

# these types are not needed by user-defined APIs. Therefore, they will not

5179

# show up in the generated discovery doc. This field should only be used

5180

# to define system APIs in ESF.

5181

{ # A protocol buffer message type.

5182

"fields": [ # The list of fields.

5183

{ # A single field of a message type.

5184

"number": 42, # The field number.

5185

"name": "A String", # The field name.

5186

"kind": "A String", # The field type.

5187

"jsonName": "A String", # The field JSON name.

5188

"cardinality": "A String", # The field cardinality.

5189

"options": [ # The protocol buffer options.

5190

{ # A protocol buffer option, which can be attached to a message, field,

5191

# enumeration, etc.

5192

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5193

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5194

# For custom options, it should be the fully-qualified name. For example,

5195

# `"google.api.http"`.

5196

"value": { # The option's value packed in an Any message. If the value is a primitive,

5197

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5198

# should be used. If the value is an enum, it should be stored as an int32

5199

# value using the google.protobuf.Int32Value type.

5200

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5205

"packed": True or False, # Whether to use alternative packed wire representation.

5206

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5207

# types. The first type has index 1; zero means the type is not in the list.

5208

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5209

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5210

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5211

],

5212

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5213

"A String",

5214

],

5215

"name": "A String", # The fully qualified message name.

5216

"options": [ # The protocol buffer options.

5217

{ # A protocol buffer option, which can be attached to a message, field,

5218

# enumeration, etc.

5219

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5220

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5221

# For custom options, it should be the fully-qualified name. For example,

5222

# `"google.api.http"`.

5223

"value": { # The option's value packed in an Any message. If the value is a primitive,

5224

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5225

# should be used. If the value is an enum, it should be stored as an int32

5226

# value using the google.protobuf.Int32Value type.

5227

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"syntax": "A String", # The source syntax.

5232

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5233

# protobuf element, like the file in which it is defined.

5234

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5235

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"logging": { # Logging configuration of the service. # Logging configuration.

5240

#

5241

# The following example shows how to configure logs to be sent to the

5242

# producer and consumer projects. In the example, the `activity_history`

5243

# log is sent to both the producer and consumer projects, whereas the

5244

# `purchase_history` log is only sent to the producer project.

5245

#

5246

# monitored_resources:

5247

# - type: library.googleapis.com/branch

5248

# labels:

5249

# - key: /city

5250

# description: The city where the library branch is located in.

5251

# - key: /name

5252

# description: The name of the branch.

5253

# logs:

5254

# - name: activity_history

5255

# labels:

5256

# - key: /customer_id

5257

# - name: purchase_history

5258

# logging:

5259

# producer_destinations:

5260

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

5265

# - monitored_resource: library.googleapis.com/branch

5266

# logs:

5267

# - activity_history

5268

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5269

# There can be multiple consumer destinations, each one must have a

5270

# different monitored resource type. A log can be used in at most

5271

# one consumer destination.

5272

{ # Configuration of a specific logging destination (the producer project

5273

# or the consumer project).

5274

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

5275

# Service.monitored_resources section.

5276

"logs": [ # Names of the logs to be sent to this destination. Each name must

5277

# be defined in the Service.logs section. If the log name is

5278

# not a domain scoped name, it will be automatically prefixed with

5279

# the service name followed by "/".

"A String",

],

},

],

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5285

# There can be multiple producer destinations, each one must have a

5286

# different monitored resource type. A log can be used in at most

5287

# one producer destination.

5288

{ # Configuration of a specific logging destination (the producer project

5289

# or the consumer project).

5290

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

5291

# Service.monitored_resources section.

5292

"logs": [ # Names of the logs to be sent to this destination. Each name must

5293

# be defined in the Service.logs section. If the log name is

5294

# not a domain scoped name, it will be automatically prefixed with

5295

# the service name followed by "/".

"A String",

],

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5302

# by the Service.monitoring and Service.logging configurations.

5303

{ # An object that describes the schema of a MonitoredResource object using a

5304

# type name and a set of labels. For example, the monitored resource

5305

# descriptor for Google Compute Engine VM instances has a type of

5306

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5307

# `"zone"` to identify particular VM instances.

5308

#

5309

# Different APIs can support different monitored resource types. APIs generally

5310

# provide a `list` method that returns the monitored resource descriptors used

5311

# by the API.

5312

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

5313

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5314

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5315

# {type} is the value of the `type` field in this object and

5316

# {project_id} is a project ID that provides API-specific context for

5317

# accessing the type. APIs that do not use project information can use the

5318

# resource name format `"monitoredResourceDescriptors/{type}"`.

5319

"labels": [ # Required. A set of labels used to describe instances of this monitored

5320

# resource type. For example, an individual Google Cloud SQL database is

5321

# identified by values for the labels `"database_id"` and `"zone"`.

5322

{ # A description of a label.

5323

"valueType": "A String", # The type of data that can be assigned to the label.

5324

"key": "A String", # The label key.

5325

"description": "A String", # A human-readable description for the label.

5326

},

5327

],

5328

"type": "A String", # Required. The monitored resource type. For example, the type

5329

# `"cloudsql_database"` represents databases in Google Cloud SQL.

5330

# The maximum length of this value is 256 characters.

5331

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5332

# be used in documentation.

5333

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5334

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5335

# without any article or other determiners. For example,

5336

# `"Google Cloud SQL Database"`.

5337

},

5338

],

5339

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

5340

#

5341

# The example below shows how to configure monitored resources and metrics

5342

# for monitoring. In the example, a monitored resource and two metrics are

5343

# defined. The `library.googleapis.com/book/returned_count` metric is sent

5344

# to both producer and consumer projects, whereas the

5345

# `library.googleapis.com/book/overdue_count` metric is only sent to the

5346

# consumer project.

5347

#

5348

# monitored_resources:

5349

# - type: library.googleapis.com/branch

5350

# labels:

5351

# - key: /city

5352

# description: The city where the library branch is located in.

5353

# - key: /name

5354

# description: The name of the branch.

5355

# metrics:

5356

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

5361

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

5366

# monitoring:

5367

# producer_destinations:

5368

# - monitored_resource: library.googleapis.com/branch

5369

# metrics:

5370

# - library.googleapis.com/book/returned_count

5371

# consumer_destinations:

5372

# - monitored_resource: library.googleapis.com/branch

5373

# metrics:

5374

# - library.googleapis.com/book/returned_count

5375

# - library.googleapis.com/book/overdue_count

5376

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

5377

# There can be multiple producer destinations. A monitored resouce type may

5378

# appear in multiple monitoring destinations if different aggregations are

5379

# needed for different sets of metrics associated with that monitored

5380

# resource type. A monitored resource and metric pair may only be used once

5381

# in the Monitoring configuration.

5382

{ # Configuration of a specific monitoring destination (the producer project

5383

# or the consumer project).

5384

"metrics": [ # Types of the metrics to report to this monitoring destination.

5385

# Each type must be defined in Service.metrics section.

5386

"A String",

5387

],

5388

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5389

# Service.monitored_resources section.

5390

},

5391

],

5392

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

5393

# There can be multiple consumer destinations. A monitored resouce type may

5394

# appear in multiple monitoring destinations if different aggregations are

5395

# needed for different sets of metrics associated with that monitored

5396

# resource type. A monitored resource and metric pair may only be used once

5397

# in the Monitoring configuration.

5398

{ # Configuration of a specific monitoring destination (the producer project

5399

# or the consumer project).

5400

"metrics": [ # Types of the metrics to report to this monitoring destination.

5401

# Each type must be defined in Service.metrics section.

5402

"A String",

5403

],

5404

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5405

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5406

},

5407

],

5408

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5409

"systemParameters": { # ### System parameter configuration # System parameter configuration.

5410

#

5411

# A system parameter is a special kind of parameter defined by the API

5412

# system, not by an individual API. It is typically mapped to an HTTP header

5413

# and/or a URL query parameter. This configuration specifies which methods

5414

# change the names of the system parameters.

5415

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5416

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5417

# The parameters defined here will override the default parameters

5418

# implemented by the system. If this field is missing from the service

5419

# config, default system parameters will be used. Default system parameters

5420

# and names is implementation-dependent.

5421

#

5422

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

5430

#

5431

#

5432

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

5437

# parameters:

5438

# - name: api_key

5439

# http_header: Api-Key1

5440

# - name: api_key

5441

# http_header: Api-Key2

5442

#

5443

# **NOTE:** All service configuration rules follow "last one wins" order.

5444

{ # Define a system parameter rule mapping system parameter definitions to

5445

# methods.

5446

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

5447

# For a given method call, only one of them should be used. If multiple

5448

# names are used the behavior is implementation-dependent.

5449

# If none of the specified names are present the behavior is

5450

# parameter-dependent.

5451

{ # Define a parameter's name and location. The parameter may be passed as either

5452

# an HTTP header or a URL query parameter, and if both are passed the behavior

5453

# is implementation-dependent.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5454

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

5455

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

5456

# sensitive.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5457

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

5458

# insensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5459

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5460

],

5461

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5462

# methods in all APIs.

5463

#

5464

# Refer to selector for syntax details.

5465

},

5466

],

5467

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5468

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

5469

# usage.

5470

#

5471

# The metric based quota configuration works this way:

5472

# - The service configuration defines a set of metrics.

5473

# - For API calls, the quota.metric_rules maps methods to metrics with

5474

# corresponding costs.

5475

# - The quota.limits defines limits on the metrics, which will be used for

5476

# quota checks at runtime.

5477

#

5478

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

5484

# metric: library.googleapis.com/write_calls

5485

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

5491

# # except for the UpdateBook and DeleteBook methods. These two methods

5492

# # are mapped to the write_calls metric, with the UpdateBook method

5493

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

5498

# - selector: google.example.library.v1.LibraryService.UpdateBook

5499

# metric_costs:

5500

# library.googleapis.com/write_calls: 2

5501

# - selector: google.example.library.v1.LibraryService.DeleteBook

5502

# metric_costs:

5503

# library.googleapis.com/write_calls: 1

5504

#

5505

# Corresponding Metric definition:

5506

#

5507

# metrics:

5508

# - name: library.googleapis.com/read_calls

5509

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

5514

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

5519

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

5520

# for a limit type. There can be at most one limit for a duration and limit

5521

# type combination defined within a `QuotaGroup`.

5522

"displayName": "A String", # User-visible display name for this limit.

5523

# Optional. If not set, the UI will provide a default display name based on

5524

# the quota configuration. This field can be used to override the default

5525

# display name generated from the configuration.

5526

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

5527

# duration. Client application developers can override the default limit up

5528

# to this maximum. If specified, this value cannot be set to a value less

5529

# than the default limit. If not specified, it is set to the default limit.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5530

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5531

# To allow clients to apply overrides with no upper bound, set this to -1,

5532

# indicating unlimited maximum quota.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5533

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5534

# Used by group-based quotas only.

5535

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5536

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5537

# Used by group-based quotas only.

5538

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

5539

# The free tier is the number of tokens that will be subtracted from the

5540

# billed amount when billing is enabled.

5541

# This field can only be set on a limit with duration "1d", in a billable

5542

# group; it is invalid on any other limit. If this field is not set, it

5543

# defaults to 0, indicating that there is no free tier for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5544

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5545

# Used by group-based quotas only.

5546

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

5547

# Metric.unit. The supported unit kinds are determined by the quota

5548

# backend system.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5549

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5550

# Here are some examples:

5551

# * "1/min/{project}" for quota per minute per project.

5552

#

5553

# Note: the order of unit components is insignificant.

5554

# The "1" at the beginning is required to follow the metric unit syntax.

5555

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

5556

# duration. This is the number of tokens assigned when a client

5557

# application developer activates the service for his/her project.

5558

#

5559

# Specifying a value of 0 will block all requests. This can be used if you

5560

# are provisioning quota to selected consumers and blocking others.

5561

# Similarly, a value of -1 will indicate an unlimited quota. No other

5562

# negative values are allowed.

5563

#

5564

# Used by group-based quotas only.

5565

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

5566

# integer value that is the maximum number of requests allowed for the

5567

# specified unit. Currently only STANDARD is supported.

5568

"a_key": "A String",

5569

},

5570

"name": "A String", # Name of the quota limit.

5571

#

5572

# The name must be provided, and it must be unique within the service. The

5573

# name can only include alphanumeric characters as well as '-'.

5574

#

5575

# The maximum length of the limit name is 64 characters.

5576

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

5577

# the same metric will be checked together during runtime. The metric must be

5578

# defined within the service config.

5579

"description": "A String", # Optional. User-visible, extended description for this quota limit.

5580

# Should be used only when more context is needed to understand this limit

5581

# than provided by the limit's display name (see: `display_name`).

5582

},

5583

],

5584

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

5585

# or more metrics.

5586

{ # Bind API methods to metrics. Binding a method to a metric causes that

5587

# metric's configured quota behaviors to apply to the method call.

5588

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

5589

# cost applied to each metric.

5590

#

5591

# The key of the map is the metric name, and the values are the amount

5592

# increased for the metric against which the quota limits are defined.

5593

# The value must not be negative.

5594

"a_key": "A String",

5595

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5596

"selector": "A String", # Selects the methods to which this rule applies.

5597

#

5598

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5599

},

5600

],

5601

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5602

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5603

#

5604

# Example:

5605

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

5611

# - google.rpc.context.OriginContext

5612

#

5613

# The above specifies that all methods in the API request

5614

# `google.rpc.context.ProjectContext` and

5615

# `google.rpc.context.OriginContext`.

5616

#

5617

# Available context types are defined in package

5618

# `google.rpc.context`.

5619

#

5620

# This also provides mechanism to whitelist any protobuf message extension that

5621

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

5622

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

5623

# 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"

5631

# allowed_request_extensions:

5632

# - google.foo.v1.NewExtension

5633

# allowed_response_extensions:

5634

# - google.foo.v1.NewExtension

5635

#

5636

# You can also specify extension ID instead of fully qualified extension name

5637

# here.

5638

"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]

5639

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5640

# **NOTE:** All service configuration rules follow "last one wins" order.

5641

{ # A context rule provides information about the context for an individual API

5642

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5643

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5644

# side channel from client to backend.

5645

"A String",

5646

],

5647

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5648

# side channel from backend to client.

5649

"A String",

5650

],

5651

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5652

#

5653

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5654

"requested": [ # A list of full type names of requested contexts.

5655

"A String",

5656

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5657

"provided": [ # A list of full type names of provided contexts.

5658

"A String",

5659

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5660

},

5661

],

5662

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5663

"producerProjectId": "A String", # The Google project that owns this service.

5664

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

5665

"rules": [ # A list of API backend rules that apply to individual API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5666

#

5667

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5668

{ # A backend rule provides configuration for an individual API element.

5669

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

5670

# operation. The default is no deadline.

5671

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

5672

# value lower than this will be rejected.

5673

"address": "A String", # The address of the API backend.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5674

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5675

# The scheme is used to determine the backend protocol and security.

5676

# The following schemes are accepted:

5677

#

5678

# 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

5685

# may cause constrasting behaviors across platforms.

5686

#

5687

# If the port is unspecified, the default is:

5688

# - 80 for schemes without TLS

5689

# - 443 for schemes with TLS

5690

#

5691

# For HTTP backends, use protocol

5692

# to specify the protocol version.

5693

"pathTranslation": "A String",

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5694

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5695

#

5696

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5697

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

5698

# This ID token will be added in the HTTP "authorization" header, and sent

5699

# to the backend.

5700

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

5701

# original "Authorization" HTTP header will be preserved. If the header is

5702

# used to carry the original token and is expected by the backend, this

5703

# field must be set to true to preserve the header.

5704

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

5705

# varies based on the request protocol and deployment environment.

5706

"protocol": "A String", # The protocol used for sending a request to the backend.

5707

# The supported values are "http/1.1" and "h2".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5708

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5709

# The default value is inferred from the scheme in the

5710

# address field:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5711

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5717

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5718

# For secure HTTP backends (https://) that support HTTP/2, set this field

5719

# to "h2" for improved performance.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5720

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5721

# Configuring this field to non-default values is only supported for secure

5722

# HTTP backends. This field will be ignored for all other backends.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5723

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5724

# See

5725

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

5726

# for more details on the supported values.

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]

5734

<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]

5735

<pre>Lists the history of the service configuration for a managed service,

5736

from the newest to the oldest.

5737

5738

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5739

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]

5740

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5741

pageToken: string, The token of the page to retrieve.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5742

pageSize: integer, The max number of items to include in the response list. Page size is 50

5743

if not specified. Maximum value is 100.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5744

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5751

5752

{ # Response message for ListServiceConfigs method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5753

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5754

{ # `Service` is the root object of Google service configuration schema. It

5755

# describes basic information about a service, such as the name and the

5756

# title, and delegates other aspects to sub-sections. Each sub-section is

5757

# either a proto message or a repeated proto message that configures a

5758

# 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]

5763

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5764

# name: calendar.googleapis.com

5765

# title: Google Calendar API

5766

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5767

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5768

# authentication:

5769

# providers:

5770

# - id: google_calendar_auth

5771

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5772

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5773

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5774

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5775

# requirements:

5776

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5777

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

5778

# service controller handles features like abuse, quota, billing, logging,

5779

# monitoring, etc.

5780

"environment": "A String", # The service control environment to use. If empty, no control plane

5781

# feature (like quota and billing) will be enabled.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5782

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5783

"types": [ # A list of all proto message types included in this API service.

5784

# Types referenced directly or indirectly by the `apis` are

5785

# automatically included. Messages which are not referenced but

5786

# shall be included, such as types used by the `google.protobuf.Any` type,

5787

# should be listed here by name. Example:

5788

#

5789

# types:

5790

# - name: google.protobuf.Int32

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5791

{ # A protocol buffer message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5792

"fields": [ # The list of fields.

5793

{ # A single field of a message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5794

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5795

"name": "A String", # The field name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5796

"kind": "A String", # The field type.

5797

"jsonName": "A String", # The field JSON name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5798

"cardinality": "A String", # The field cardinality.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5799

"options": [ # The protocol buffer options.

5800

{ # A protocol buffer option, which can be attached to a message, field,

5801

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5802

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5803

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5804

# For custom options, it should be the fully-qualified name. For example,

5805

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5806

"value": { # The option's value packed in an Any message. If the value is a primitive,

5807

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5808

# should be used. If the value is an enum, it should be stored as an int32

5809

# value using the google.protobuf.Int32Value type.

5810

"a_key": "", # Properties of the object. Contains field @type with type URL.

5811

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5812

},

5813

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5814

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5815

"packed": True or False, # Whether to use alternative packed wire representation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5816

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5817

# types. The first type has index 1; zero means the type is not in the list.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5818

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5819

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5820

},

5821

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5822

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5823

"A String",

5824

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5825

"name": "A String", # The fully qualified message name.

5826

"options": [ # The protocol buffer options.

5827

{ # A protocol buffer option, which can be attached to a message, field,

5828

# enumeration, etc.

5829

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5830

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5831

# For custom options, it should be the fully-qualified name. For example,

5832

# `"google.api.http"`.

5833

"value": { # The option's value packed in an Any message. If the value is a primitive,

5834

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5835

# should be used. If the value is an enum, it should be stored as an int32

5836

# value using the google.protobuf.Int32Value type.

5837

"a_key": "", # Properties of the object. Contains field @type with type URL.

5838

},

5839

},

5840

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5841

"syntax": "A String", # The source syntax.

5842

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5843

# protobuf element, like the file in which it is defined.

5844

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5845

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5846

},

5847

},

5848

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5849

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

5850

"sourceFiles": [ # All files used during config generation.

5851

{

5852

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

},

],

},

"name": "A String", # The service name, which is a DNS-like logical identifier for the

5857

# service, such as `calendar.googleapis.com`. The service name

5858

# typically goes through DNS verification to make sure the owner

5859

# of the service also owns the DNS name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5860

"title": "A String", # The product title for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5861

"logs": [ # Defines the logs used by this service.

5862

{ # A description of a log type. Example in YAML format:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5863

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5864

# - name: library.googleapis.com/activity_history

5865

# description: The history of borrowing and returning library items.

5866

# display_name: Activity

5867

# labels:

5868

# - key: /customer_id

5869

# description: Identifier of a library customer

5870

"labels": [ # The set of labels that are available to describe a specific log entry.

5871

# Runtime requests that contain labels not specified here are

5872

# considered invalid.

5873

{ # A description of a label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5874

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5875

"key": "A String", # The label key.

5876

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5877

},

5878

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5879

"description": "A String", # A human-readable description of this log. This information appears in

5880

# the documentation and can contain details.

5881

"displayName": "A String", # The human-readable name for this log. This information appears on

5882

# the user interface and should be concise.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5883

"name": "A String", # The name of the log. It must be less than 512 characters long and can

5884

# include the following characters: upper- and lower-case alphanumeric

5885

# characters [A-Za-z0-9], and punctuation characters including

5886

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5887

},

5888

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

5889

"metrics": [ # Defines the metrics used by this service.

5890

{ # Defines a metric type and its schema. Once a metric descriptor is created,

5891

# deleting or altering it stops data collection and makes the metric type's

5892

# existing data unusable.

5893

"type": "A String", # The metric type, including its DNS name prefix. The type is not

5894

# URL-encoded. All user-defined metric types have the DNS name

5895

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

5896

# use a natural hierarchical grouping. For example:

5897

#

5898

# "custom.googleapis.com/invoice/paid/amount"

5899

# "external.googleapis.com/prometheus/up"

5900

# "appengine.googleapis.com/http/server/response_latencies"

5901

"labels": [ # The set of labels that can be used to describe a specific

5902

# instance of this metric type. For example, the

5903

# `appengine.googleapis.com/http/server/response_latencies` metric

5904

# type has a label for the HTTP response code, `response_code`, so

5905

# you can look at latencies for successful responses or just

5906

# for responses that failed.

5907

{ # A description of a label.

5908

"valueType": "A String", # The type of data that can be assigned to the label.

5909

"key": "A String", # The label key.

5910

"description": "A String", # A human-readable description for the label.

5911

},

5912

],

5913

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5914

"monitoredResourceTypes": [ # Read-only. If present, then a time

5915

# series, which is identified partially by

5916

# a metric type and a MonitoredResourceDescriptor, that is associated

5917

# with this metric type can only be associated with one of the monitored

5918

# resource types listed here.

5919

"A String",

5920

],

5921

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5922

# Use sentence case without an ending period, for example "Request count".

5923

# This field is optional but it is recommended to be set for any metrics

5924

# associated with user-visible concepts, such as Quota.

5925

"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.

5926

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

5927

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

5928

# age are guaranteed to be ingested and available to be read, excluding

5929

# data loss due to errors.

5930

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

5931

# periodically, consecutive data points are stored at this time interval,

5932

# excluding data loss due to errors. Metrics with a higher granularity have

5933

# a smaller sampling period.

5934

},

5935

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

5936

# Some combinations of `metric_kind` and `value_type` might not be supported.

5937

"unit": "A String", # The units in which the metric value is reported. It is only applicable

5938

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

5939

# defines the representation of the stored metric values.

5940

#

5941

# Different systems may scale the values to be more easily displayed (so a

5942

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

5943

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

5944

# `KBy`, then the value of the metric is always in thousands of bytes, no

5945

# matter how it may be displayed..

5946

#

5947

# If you want a custom metric to record the exact number of CPU-seconds used

5948

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

5949

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

5950

# CPU-seconds, then the value is written as `12005`.

5951

#

5952

# Alternatively, if you want a custom metric to record data in a more

5953

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

5954

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

5955

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

5956

#

5957

# The supported units are a subset of [The Unified Code for Units of

5958

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5959

#

5960

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

5978

# * `Y` yotta (10^24)

5979

#

5980

# * `m` milli (10^-3)

5981

# * `u` micro (10^-6)

5982

# * `n` nano (10^-9)

5983

# * `p` pico (10^-12)

5984

# * `f` femto (10^-15)

5985

# * `a` atto (10^-18)

5986

# * `z` zepto (10^-21)

5987

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

#

# **Grammar**

#

# The grammar also includes these connectors:

5998

#

5999

# * `/` division or ratio (as an infix operator). For examples,

6000

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

6001

# have `/s` in a metric `unit`; rates should always be computed at

6002

# query time from the underlying cumulative or delta value).

6003

# * `.` multiplication or composition (as an infix operator). For

6004

# examples, `GBy.d` or `k{watt}.h`.

6005

#

6006

# The grammar for a unit is as follows:

6007

#

6008

# Expression = Component { "." Component } { "/" Component } ;

6009

#

6010

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

6020

# is used alone, then the unit is equivalent to `1`. For examples,

6021

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

6022

# * `NAME` is a sequence of non-blank printable ASCII characters not

6023

# containing `{` or `}`.

6024

# * `1` represents a unitary [dimensionless

6025

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

6026

# as in `1/s`. It is typically used when none of the basic units are

6027

# appropriate. For example, "new users per day" can be represented as

6028

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

6029

# users). Alternatively, "thousands of page views per day" would be

6030

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

6031

# value of `5.3` would mean "5300 page views per day").

6032

# * `%` represents dimensionless value of 1/100, and annotates values giving

6033

# a percentage (so the metric values are typically in the range of 0..100,

6034

# and a metric value `3` means "3 percent").

6035

# * `10^2.%` indicates a metric contains a ratio, typically in the range

6036

# 0..1, that will be multiplied by 100 and displayed as a percentage

6037

# (so a metric value `0.03` means "3 percent").

6038

"launchStage": "A String", # Optional. The launch stage of the metric definition.

6039

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

6040

# Some combinations of `metric_kind` and `value_type` might not be supported.

6041

"name": "A String", # The resource name of the metric descriptor.

6042

},

6043

],

6044

"enums": [ # A list of all enum types included in this API service. Enums

6045

# referenced directly or indirectly by the `apis` are automatically

6046

# included. Enums which are not referenced but shall be included

6047

# should be listed here by name. Example:

6048

#

6049

# enums:

6050

# - name: google.someapi.v1.SomeEnum

6051

{ # Enum type definition.

6052

"options": [ # Protocol buffer options.

6053

{ # A protocol buffer option, which can be attached to a message, field,

6054

# enumeration, etc.

6055

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6056

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6057

# For custom options, it should be the fully-qualified name. For example,

6058

# `"google.api.http"`.

6059

"value": { # The option's value packed in an Any message. If the value is a primitive,

6060

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6061

# should be used. If the value is an enum, it should be stored as an int32

6062

# value using the google.protobuf.Int32Value type.

6063

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

6068

"syntax": "A String", # The source syntax.

6069

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6070

# protobuf element, like the file in which it is defined.

6071

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6072

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6073

},

6074

"enumvalue": [ # Enum value definitions.

6075

{ # Enum value definition.

6076

"name": "A String", # Enum value name.

6077

"number": 42, # Enum value number.

6078

"options": [ # Protocol buffer options.

6079

{ # A protocol buffer option, which can be attached to a message, field,

6080

# enumeration, etc.

6081

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6082

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6083

# For custom options, it should be the fully-qualified name. For example,

6084

# `"google.api.http"`.

6085

"value": { # The option's value packed in an Any message. If the value is a primitive,

6086

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6087

# should be used. If the value is an enum, it should be stored as an int32

6088

# value using the google.protobuf.Int32Value type.

6089

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

},

],

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

6098

#

6099

# Example for an API targeted for external use:

6100

#

6101

# name: calendar.googleapis.com

6102

# authentication:

6103

# providers:

6104

# - id: google_calendar_auth

6105

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

6106

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

6111

"rules": [ # A list of authentication rules that apply to individual API methods.

6112

#

6113

# **NOTE:** All service configuration rules follow "last one wins" order.

6114

{ # Authentication rules for the service.

6115

#

6116

# By default, if a method has any authentication requirements, every request

6117

# must include a valid credential matching one of the requirements.

6118

# It's an error to include more than one kind of credential in a single

6119

# request.

6120

#

6121

# If a method doesn't have any auth requirements, request credentials will be

6122

# ignored.

6123

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

6124

# there are scopes defined for "Read-only access to Google Calendar" and

6125

# "Access to Cloud Platform". Users can consent to a scope for an application,

6126

# giving it permission to access that data on their behalf.

6127

#

6128

# OAuth scope specifications should be fairly coarse grained; a user will need

6129

# to see and understand the text description of what your scope means.

6130

#

6131

# In most cases: use one or at most two OAuth scopes for an entire family of

6132

# products. If your product has multiple APIs, you should probably be sharing

6133

# the OAuth scope across all of those APIs.

6134

#

6135

# When you need finer grained OAuth consent screens: talk with your product

6136

# management about how developers will use them in practice.

6137

#

6138

# Please note that even though each of the canonical scopes is enough for a

6139

# request to be accepted and passed to the backend, a request can still fail

6140

# due to the backend requiring additional scopes or permissions.

6141

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

6142

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

6147

# https://www.googleapis.com/auth/calendar.read

6148

},

6149

"requirements": [ # Requirements for additional authentication providers.

6150

{ # User-defined authentication requirements, including support for

6151

# [JSON Web Token

6152

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

6153

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

6154

# implemented and accepted in all the runtime components.

6155

#

6156

# The list of JWT

6157

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

6158

# that are allowed to access. A JWT containing any of these audiences will

6159

# be accepted. When this setting is absent, only JWTs with audience

6160

# "https://Service_name/API_name"

6161

# will be accepted. For example, if no audiences are in the setting,

6162

# LibraryService API will only accept JWTs with the following audience

6163

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

6168

# bookstore_web.apps.googleusercontent.com

6169

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

6174

},

6175

],

6176

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

6177

"selector": "A String", # Selects the methods to which this rule applies.

6178

#

6179

# Refer to selector for syntax details.

6180

},

6181

],

6182

"providers": [ # Defines a set of authentication providers that a service supports.

6183

{ # Configuration for an authentication provider, including support for

6184

# [JSON Web Token

6185

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

6186

"audiences": "A String", # The list of JWT

6187

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

6188

# that are allowed to access. A JWT containing any of these audiences will

6189

# be accepted. When this setting is absent, JWTs with audiences:

6190

# - "https://[service.name]/[google.protobuf.Api.name]"

6191

# - "https://[service.name]/"

6192

# will be accepted.

6193

# For example, if no audiences are in the setting, LibraryService API will

6194

# accept JWTs with the following audiences:

6195

# -

6196

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

6197

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

6202

# bookstore_web.apps.googleusercontent.com

6203

"jwtLocations": [ # Defines the locations to extract the JWT.

6204

#

6205

# JWT locations can be either from HTTP headers or URL query parameters.

6206

# The rule is that the first match wins. The checking order is: checking

6207

# all headers first, then URL query parameters.

6208

#

6209

# If not specified, default to use following 3 locations:

6210

# 1) Authorization: Bearer

6211

# 2) x-goog-iap-jwt-assertion

6212

# 3) access_token query parameter

6213

#

6214

# Default locations can be specified as followings:

6215

# jwt_locations:

6216

# - header: Authorization

6217

# value_prefix: "Bearer "

6218

# - header: x-goog-iap-jwt-assertion

6219

# - query: access_token

6220

{ # Specifies a location to extract JWT from an API request.

6221

"query": "A String", # Specifies URL query parameter name to extract JWT token.

6222

"header": "A String", # Specifies HTTP header name to extract JWT token.

6223

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

6224

# Only applies to "in" header type. Must be empty for "in" query type.

6225

# If not empty, the header value has to match (case sensitive) this prefix.

6226

# If not matched, JWT will not be extracted. If matched, JWT will be

6227

# extracted after the prefix is removed.

6228

#

6229

# For example, for "Authorization: Bearer {JWT}",

6230

# value_prefix="Bearer " with a space at the end.

6231

},

6232

],

6233

"issuer": "A String", # Identifies the principal that issued the JWT. See

6234

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

6235

# Usually a URL or an email address.

6236

#

6237

# Example: https://securetoken.google.com

6238

# Example: 1234567-compute@developer.gserviceaccount.com

6239

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

6240

# `AuthRequirement.provider_id`.

6241

#

6242

# Example: "bookstore_auth".

6243

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

6244

# [OpenID

6245

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

6246

# Optional if the key set document:

6247

# - can be retrieved from

6248

# [OpenID

6249

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

6250

# the issuer.

6251

# - can be inferred from the email domain of the issuer (e.g. a Google

6252

# service account).

6253

#

6254

# Example: https://www.googleapis.com/oauth2/v1/certs

6255

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

6256

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

},

],

},

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

6261

#

6262

# Example:

6263

# <pre><code>documentation:

6264

# summary: >

6265

# The Google Calendar API gives access

6266

# to most calendar features.

6267

# pages:

6268

# - name: Overview

6269

# content: &#40;== include google/foo/overview.md ==&#41;

6270

# - name: Tutorial

6271

# content: &#40;== include google/foo/tutorial.md ==&#41;

6272

# subpages;

6273

# - name: Java

6274

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

6275

# rules:

6276

# - selector: google.calendar.Calendar.Get

6277

# description: >

6278

# ...

6279

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

6284

# standard markdown features, definition lists, tables and fenced

6285

# code blocks are supported. Section headers can be provided and are

6286

# interpreted relative to the section nesting of the context where

6287

# a documentation fragment is embedded.

6288

#

6289

# Documentation from the IDL is merged with documentation defined

6290

# via the config at normalization time, where documentation provided

6291

# by config rules overrides IDL provided.

6292

#

6293

# A number of constructs specific to the API platform are supported

6294

# in documentation text.

6295

#

6296

# In order to reference a proto element, the following

6297

# notation can be used:

6298

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

6299

# To override the display text used for the link, this can be used:

6300

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

6301

# Text can be excluded from doc using the following notation:

6302

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

6303

#

6304

# A few directives are available in documentation. Note that

6305

# directives must appear on a single line to be properly

6306

# identified. The `include` directive includes a markdown file from

6307

# an external source:

6308

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

6309

# The `resource_for` directive marks a message to be the resource of

6310

# a collection in REST view. If it is not specified, tools attempt

6311

# to infer the resource from the operations in a collection:

6312

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

6313

# The directive `suppress_warning` does not directly affect documentation

6314

# and is documented together with service config validation.

6315

"documentationRootUrl": "A String", # The URL to the root of documentation.

6316

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

6317

# from the yaml file) is not suitable. This can be seen in any fully

6318

# specified service urls as well as sections that show a base that other

6319

# urls are relative to.

6320

"rules": [ # A list of documentation rules that apply to individual API elements.

6321

#

6322

# **NOTE:** All service configuration rules follow "last one wins" order.

6323

{ # A documentation rule provides information about individual API elements.

6324

"description": "A String", # Description of the selected API(s).

6325

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

6326

# an element is marked as `deprecated`.

6327

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

6328

# qualified name of the element which may end in "*", indicating a wildcard.

6329

# Wildcards are only allowed at the end and for a whole component of the

6330

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

6331

# wildcard will match one or more components. To specify a default for all

6332

# applicable elements, the whole pattern "*" is used.

6333

},

6334

],

6335

"pages": [ # The top level pages for the documentation set.

6336

{ # Represents a documentation page. A page can contain subpages to represent

6337

# nested documentation set structure.

6338

"name": "A String", # The name of the page. It will be used as an identity of the page to

6339

# generate URI of the page, text of the link to this page in navigation,

6340

# etc. The full page name (start from the root page name to this page

6341

# concatenated with `.`) can be used as reference to the page in your

6342

# documentation. For example:

6343

# <pre><code>pages:

6344

# - name: Tutorial

6345

# content: &#40;== include tutorial.md ==&#41;

6346

# subpages:

6347

# - name: Java

6348

# content: &#40;== include tutorial_java.md ==&#41;

6349

# </code></pre>

6350

# You can reference `Java` page using Markdown reference link syntax:

6351

# `Java`.

6352

"subpages": [ # Subpages of this page. The order of subpages specified here will be

6353

# honored in the generated docset.

6354

# Object with schema name: Page

6355

],

6356

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

6357

# ==&#41;</code> to include content from a Markdown file.

6358

},

6359

],

6360

"summary": "A String", # A short summary of what the service does. Can only be provided by

6361

# plain text.

6362

"overview": "A String", # Declares a single overview page. For example:

6363

# <pre><code>documentation:

6364

# summary: ...

6365

# overview: &#40;== include overview.md ==&#41;

6366

# </code></pre>

6367

# This is a shortcut for the following declaration (using pages style):

6368

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

6373

# </code></pre>

6374

# Note: you cannot specify both `overview` field and `pages` field.

6375

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6376

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

6377

# of the google.protobuf.Api needs to be provided by the configuration

6378

# author, as the remaining fields will be derived from the IDL during the

6379

# normalization process. It is an error to specify an API interface here

6380

# which cannot be resolved against the associated IDL files.

6381

{ # Api is a light-weight descriptor for an API Interface.

6382

#

6383

# Interfaces are also described as "protocol buffer services" in some contexts,

6384

# such as by the "service" keyword in a .proto file, but they are different

6385

# from API Services, which represent a concrete implementation of an interface

6386

# as opposed to simply a description of methods and bindings. They are also

6387

# sometimes simply referred to as "APIs" in other contexts, such as the name of

6388

# this message itself. See https://cloud.google.com/apis/design/glossary for

6389

# detailed terminology.

6390

"options": [ # Any metadata attached to the interface.

6391

{ # A protocol buffer option, which can be attached to a message, field,

6392

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6393

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6394

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6395

# For custom options, it should be the fully-qualified name. For example,

6396

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6397

"value": { # The option's value packed in an Any message. If the value is a primitive,

6398

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6399

# should be used. If the value is an enum, it should be stored as an int32

6400

# value using the google.protobuf.Int32Value type.

6401

"a_key": "", # Properties of the object. Contains field @type with type URL.

6402

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6403

},

6404

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6405

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6406

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

6407

# message.

6408

# protobuf element, like the file in which it is defined.

6409

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6410

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6411

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6412

"mixins": [ # Included interfaces. See Mixin.

6413

{ # Declares an API Interface to be included in this interface. The including

6414

# interface must redeclare all the methods from the included interface, but

6415

# documentation and options are inherited as follows:

6416

#

6417

# - If after comment and whitespace stripping, the documentation

6418

# string of the redeclared method is empty, it will be inherited

6419

# from the original method.

6420

#

6421

# - Each annotation belonging to the service config (http,

6422

# visibility) which is not set in the redeclared method will be

6423

# inherited.

6424

#

6425

# - If an http annotation is inherited, the path pattern will be

6426

# modified as follows. Any version prefix will be replaced by the

6427

# version of the including interface plus the root path if

6428

# specified.

6429

#

6430

# Example of a simple mixin:

6431

#

6432

# package google.acl.v1;

6433

# service AccessControl {

6434

# // Get the underlying ACL object.

6435

# rpc GetAcl(GetAclRequest) returns (Acl) {

6436

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

6441

# service Storage {

6442

# // rpc GetAcl(GetAclRequest) returns (Acl);

6443

#

6444

# // Get a data record.

6445

# rpc GetData(GetDataRequest) returns (Data) {

6446

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

6451

#

6452

# apis:

6453

# - name: google.storage.v2.Storage

6454

# mixins:

6455

# - name: google.acl.v1.AccessControl

6456

#

6457

# The mixin construct implies that all methods in `AccessControl` are

6458

# also declared with same name and request/response types in

6459

# `Storage`. A documentation generator or annotation processor will

6460

# see the effective `Storage.GetAcl` method after inherting

6461

# documentation and annotations as follows:

6462

#

6463

# service Storage {

6464

# // Get the underlying ACL object.

6465

# rpc GetAcl(GetAclRequest) returns (Acl) {

6466

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

6472

#

6473

# If the `root` field in the mixin is specified, it should be a

6474

# relative path under which inherited HTTP paths are placed. Example:

6475

#

6476

# apis:

6477

# - name: google.storage.v2.Storage

6478

# mixins:

6479

# - name: google.acl.v1.AccessControl

6480

# root: acls

6481

#

6482

# This implies the following inherited HTTP annotation:

6483

#

6484

# service Storage {

6485

# // Get the underlying ACL object.

6486

# rpc GetAcl(GetAclRequest) returns (Acl) {

6487

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"name": "A String", # The fully qualified name of the interface which is included.

6492

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

6493

# are rooted.

6494

},

6495

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6496

"version": "A String", # A version string for this interface. If specified, must have the form

6497

# `major-version.minor-version`, as in `1.10`. If the minor version is

6498

# omitted, it defaults to zero. If the entire version field is empty, the

6499

# major version is derived from the package name, as outlined below. If the

6500

# field is not empty, the version in the package name will be verified to be

6501

# consistent with what is provided here.

6502

#

6503

# The versioning schema uses [semantic

6504

# versioning](http://semver.org) where the major version number

6505

# indicates a breaking change and the minor version an additive,

6506

# non-breaking change. Both version numbers are signals to users

6507

# what to expect from different versions, and should be carefully

6508

# chosen based on the product plan.

6509

#

6510

# The major version is also reflected in the package name of the

6511

# interface, which must end in `v<major-version>`, as in

6512

# `google.feature.v1`. For major versions 0 and 1, the suffix can

6513

# be omitted. Zero major versions must only be used for

6514

# experimental, non-GA interfaces.

6515

"methods": [ # The methods of this interface, in unspecified order.

6516

{ # Method represents a method of an API interface.

6517

"requestTypeUrl": "A String", # A URL of the input message type.

6518

"name": "A String", # The simple name of this method.

6519

"responseStreaming": True or False, # If true, the response is streamed.

6520

"requestStreaming": True or False, # If true, the request is streamed.

6521

"options": [ # Any metadata attached to the method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6522

{ # A protocol buffer option, which can be attached to a message, field,

6523

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6524

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6525

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6526

# For custom options, it should be the fully-qualified name. For example,

6527

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6528

"value": { # The option's value packed in an Any message. If the value is a primitive,

6529

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6530

# should be used. If the value is an enum, it should be stored as an int32

6531

# value using the google.protobuf.Int32Value type.

6532

"a_key": "", # Properties of the object. Contains field @type with type URL.

6533

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6534

},

6535

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6536

"syntax": "A String", # The source syntax of this method.

6537

"responseTypeUrl": "A String", # The URL of the output message type.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6538

},

6539

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6540

"name": "A String", # The fully qualified name of this interface, including package name

6541

# followed by the interface's simple name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6542

},

6543

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6544

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

6545

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

6553

# - google.foo.v1.AnotherError

6554

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

6555

"A String",

6556

],

6557

"rules": [ # The list of custom error rules that apply to individual API messages.

6558

#

6559

# **NOTE:** All service configuration rules follow "last one wins" order.

6560

{ # A custom error rule.

6561

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

6562

# objects of this type will be filtered when they appear in error payload.

6563

"selector": "A String", # Selects messages to which this rule applies.

6564

#

6565

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6566

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6567

],

6568

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6569

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

6570

# by the client for tracking purpose. Must be no longer than 63 characters

6571

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

6572

# empty, the server may choose to generate one instead.

6573

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

6574

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

6575

# service. Each requirement is of the form <service.name>/<requirement-id>;

6576

# for example 'serviceusage.googleapis.com/billing-enabled'.

6577

"A String",

6578

],

6579

"rules": [ # A list of usage rules that apply to individual API methods.

6580

#

6581

# **NOTE:** All service configuration rules follow "last one wins" order.

6582

{ # Usage configuration rules for the service.

6583

#

6584

# NOTE: Under development.

6585

#

6586

#

6587

# Use this rule to configure unregistered calls for the service. Unregistered

6588

# calls are calls that do not contain consumer project identity.

6589

# (Example: calls that do not contain an API key).

6590

# By default, API methods do not allow unregistered calls, and each method call

6591

# must be identified by a consumer project identity. Use this rule to

6592

# allow/disallow unregistered calls.

6593

#

6594

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

6600

#

6601

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

6606

# allow_unregistered_calls: true

6607

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

6608

# methods in all APIs.

6609

#

6610

# Refer to selector for syntax details.

6611

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

6612

# that don't identify any user or application.

6613

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

6614

# plane features, such as quota and billing, will not be available.

6615

# This flag is used by Google Cloud Endpoints to bypass checks for internal

6616

# methods, such as service health check methods.

6617

},

6618

],

6619

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

6620

# service producer.

6621

#

6622

# Google Service Management currently only supports

6623

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

6624

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

6625

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

6626

# documented in https://cloud.google.com/pubsub/docs/overview.

6627

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

6628

#

6629

#

6630

# Use this field to configure per-product per-project service identity.

6631

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

6636

# display_name: "Cloud XXX Service Agent"

6637

# description: "Used as the identity of Cloud XXX to access resources"

6638

"displayName": "A String", # Optional. A user-specified name for the service account.

6639

# Must be less than or equal to 100 UTF-8 bytes.

6640

"description": "A String", # Optional. A user-specified opaque description of the service account.

6641

# Must be less than or equal to 256 UTF-8 bytes.

6642

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

6643

#

6644

# An example name would be:

6645

# `projects/123456789`

6646

},

6647

},

6648

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

6649

# with the same name as the service is automatically generated to service all

6650

# defined APIs.

6651

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

6652

# A service may expose any number of endpoints, and all endpoints share the

6653

# same service configuration, such as quota configuration and monitoring

6654

# configuration.

6655

#

6656

# Example service configuration:

6657

#

6658

# name: library-example.googleapis.com

6659

# endpoints:

6660

# # Below entry makes 'google.example.library.v1.Library'

6661

# # API be served from endpoint address library-example.googleapis.com.

6662

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

6663

# # it to decide whether the subsequent cross-origin request is

6664

# # allowed to proceed.

6665

# - name: library-example.googleapis.com

6666

# allow_cors: true

6667

"name": "A String", # The canonical name of this endpoint.

6668

"target": "A String", # The specification of an Internet routable address of API frontend that will

6669

# handle requests to this [API

6670

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

6671

# either a valid IPv4 address or a fully-qualified domain name. For example,

6672

# "8.8.8.8" or "myservice.appspot.com".

6673

"allowCors": True or False, # Allowing

6674

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

6675

# cross-domain traffic, would allow the backends served from this endpoint to

6676

# receive and respond to HTTP OPTIONS requests. The response will be used by

6677

# the browser to determine whether the subsequent cross-origin request is

6678

# allowed to proceed.

6679

"features": [ # The list of features enabled on this endpoint.

6680

"A String",

6681

],

6682

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

6683

# please specify multiple google.api.Endpoint for each of the intended

6684

# aliases.

6685

#

6686

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"configVersion": 42, # The semantic version of the service configuration. The config version

6692

# affects the interpretation of the service configuration. For example,

6693

# certain features are enabled by default for certain config versions.

6694

#

6695

# The latest config version is `3`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6696

"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]

6697

# HttpRule, each specifying the mapping of an RPC method

6698

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6699

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

6700

#

6701

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6702

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6703

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6704

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

6705

# more HTTP REST endpoints. It allows developers to build a single API service

6706

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

6707

# APIs](https://github.com/googleapis/googleapis),

6708

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

6709

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

6710

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

6711

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6712

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6713

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

6714

# how different portions of the gRPC request message are mapped to the URL

6715

# path, URL query parameters, and HTTP request body. It also controls how the

6716

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

6717

# typically specified as an `google.api.http` annotation on the gRPC method.

6718

#

6719

# Each mapping specifies a URL path template and an HTTP method. The path

6720

# template may refer to one or more fields in the gRPC request message, as long

6721

# as each field is a non-repeated field with a primitive (non-message) type.

6722

# The path template controls how fields of the request message are mapped to

6723

# the URL path.

6724

#

6725

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6726

#

6727

# service Messaging {

6728

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6729

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6730

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6731

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6732

# }

6733

# }

6734

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6735

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6736

# }

6737

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6738

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6739

# }

6740

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6741

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6742

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6743

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6744

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6745

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6746

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6747

# Any fields in the request message which are not bound by the path template

6748

# automatically become HTTP query parameters if there is no HTTP request body.

6749

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6750

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6751

# service Messaging {

6752

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6753

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6754

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6755

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6756

# }

6757

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6758

# message GetMessageRequest {

6759

# message SubMessage {

6760

# string subfield = 1;

6761

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6762

# string message_id = 1; // Mapped to URL path.

6763

# int64 revision = 2; // Mapped to URL query parameter `revision`.

6764

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6765

# }

6766

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6767

# This enables a HTTP JSON to RPC mapping as below:

6768

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6769

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6770

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6771

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6772

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

6773

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6774

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6775

# Note that fields which are mapped to URL query parameters must have a

6776

# primitive type or a repeated primitive type or a non-repeated message type.

6777

# 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]

6778

# 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]

6779

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6780

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6781

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6782

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6783

# specifies the mapping. Consider a REST update method on the

6784

# message resource collection:

6785

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6786

# service Messaging {

6787

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

6788

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6789

# patch: "/v1/messages/{message_id}"

6790

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

6795

# string message_id = 1; // mapped to the URL

6796

# Message message = 2; // mapped to the body

6797

# }

6798

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6799

# The following HTTP JSON to RPC mapping is enabled, where the

6800

# representation of the JSON in the request body is determined by

6801

# protos JSON encoding:

6802

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6803

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6804

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6805

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6806

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6807

#

6808

# The special name `*` can be used in the body mapping to define that

6809

# every field not bound by the path template should be mapped to the

6810

# request body. This enables the following alternative definition of

6811

# the update method:

6812

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6813

# service Messaging {

6814

# rpc UpdateMessage(Message) returns (Message) {

6815

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6816

# patch: "/v1/messages/{message_id}"

6817

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

6823

# string text = 2;

6824

# }

6825

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6826

#

6827

# The following HTTP JSON to RPC mapping is enabled:

6828

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6829

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6830

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6831

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6832

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6833

#

6834

# Note that when using `*` in the body mapping, it is not possible to

6835

# 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]

6836

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6837

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6838

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6839

#

6840

# It is possible to define multiple HTTP methods for one RPC by using

6841

# the `additional_bindings` option. Example:

6842

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6843

# service Messaging {

6844

# rpc GetMessage(GetMessageRequest) returns (Message) {

6845

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6846

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6847

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6848

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6849

# }

6850

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6851

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6852

# }

6853

# message GetMessageRequest {

6854

# string message_id = 1;

6855

# string user_id = 2;

6856

# }

6857

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6858

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6859

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6860

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6861

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6862

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

6863

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

6864

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6865

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6866

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6867

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6868

# 1. Leaf request fields (recursive expansion nested messages in the request

6869

# message) are classified into three categories:

6870

# - Fields referred by the path template. They are passed via the URL path.

6871

# - Fields referred by the HttpRule.body. They are passed via the HTTP

6872

# request body.

6873

# - All other fields are passed via the URL query parameters, and the

6874

# parameter name is the field path in the request message. A repeated

6875

# field can be represented as multiple query parameters under the same

6876

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6877

# 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]

6878

# are passed via URL path and HTTP request body.

6879

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

6880

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6881

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6882

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6883

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6884

# Template = "/" Segments [ Verb ] ;

6885

# Segments = Segment { "/" Segment } ;

6886

# Segment = "*" | "**" | LITERAL | Variable ;

6887

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

6888

# FieldPath = IDENT { "." IDENT } ;

6889

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6890

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6891

# The syntax `*` matches a single URL path segment. The syntax `**` matches

6892

# zero or more URL path segments, which must be the last part of the URL path

6893

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6894

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6895

# The syntax `Variable` matches part of the URL path as specified by its

6896

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6897

# matches a single path segment, its template may be omitted, e.g. `{var}`

6898

# is equivalent to `{var=*}`.

6899

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6900

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

6901

# contains any reserved character, such characters should be percent-encoded

6902

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6903

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6904

# If a variable contains exactly one path segment, such as `"{var}"` or

6905

# `"{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]

6906

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

6907

# server side does the reverse decoding. Such variables show up in the

6908

# [Discovery

6909

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6910

# `{var}`.

6911

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6912

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

6913

# 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]

6914

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6915

# 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]

6916

# unchanged. Such variables show up in the

6917

# [Discovery

6918

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6919

# `{+var}`.

6920

#

6921

# ## Using gRPC API Service Configuration

6922

#

6923

# gRPC API Service Configuration (service config) is a configuration language

6924

# for configuring a gRPC service to become a user-facing product. The

6925

# service config is simply the YAML representation of the `google.api.Service`

6926

# proto message.

6927

#

6928

# As an alternative to annotating your proto file, you can configure gRPC

6929

# transcoding in your service config YAML files. You do this by specifying a

6930

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

6931

# effect as the proto annotation. This can be particularly useful if you

6932

# have a proto that is reused in multiple services. Note that any transcoding

6933

# specified in the service config will override any matching transcoding

6934

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

6941

# - selector: example.v1.Messaging.GetMessage

6942

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

6947

# proto to JSON conversion must follow the [proto3

6948

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

6949

#

6950

# While the single segment variable follows the semantics of

6951

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

6952

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

6953

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

6954

# does not expand special characters like `?` and `#`, which would lead

6955

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

6956

# for multi segment variables.

6957

#

6958

# The path variables **must not** refer to any repeated or mapped field,

6959

# because client libraries are not capable of handling such variable expansion.

6960

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6961

# The path variables **must not** capture the leading "/" character. The reason

6962

# 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]

6963

# character. For consistency, all path variables must share the same behavior.

6964

#

6965

# Repeated message fields must not be mapped to URL query parameters, because

6966

# no client library can support such complicated mapping.

6967

#

6968

# If an API needs to use a JSON array for request or response body, it can map

6969

# the request or response body to a repeated field. However, some gRPC

6970

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6971

"selector": "A String", # Selects a method to which this rule applies.

6972

#

6973

# Refer to selector for syntax details.

6974

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

6975

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

6976

# included in the `pattern` field, such as HEAD, or "*" to leave the

6977

# HTTP method unspecified for this rule. The wild-card rule is useful

6978

# for services that provide content to Web (HTML) clients.

6979

"path": "A String", # The path matched by this custom verb.

6980

"kind": "A String", # The name of this custom HTTP verb.

6981

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6982

"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]

6983

# response body. When omitted, the entire response message will be used

6984

# as the HTTP response body.

6985

#

6986

# NOTE: The referred field must be present at the top-level of the response

6987

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

6988

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

6989

# half-duplex streaming method.

6990

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

6991

# not contain an `additional_bindings` field themselves (that is,

6992

# the nesting may only be one level deep).

6993

# Object with schema name: HttpRule

6994

],

6995

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

6996

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

6997

# resources.

6998

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6999

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

7000

# body, or `*` for mapping all request fields not captured by the path

7001

# pattern to the HTTP body, or omitted for not having any HTTP request body.

7002

#

7003

# NOTE: the referred field must be present at the top-level of the request

7004

# message type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7005

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

7006

},

7007

],

7008

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

7009

# cases of single segment matches in reserved expansion, where "%2F" will be

7010

# left encoded.

7011

#

7012

# The default behavior is to not decode RFC 6570 reserved characters in multi

7013

# segment matches.

7014

},

7015

"billing": { # Billing related configuration of the service. # Billing configuration.

7016

#

7017

# The following example shows how to configure monitored resources and metrics

7018

# for billing, `consumer_destinations` is the only supported destination and

7019

# the monitored resources need at least one label key

7020

# `cloud.googleapis.com/location` to indicate the location of the billing

7021

# usage, using different monitored resources between monitoring and billing is

7022

# recommended so they can be evolved independently:

7023

#

7024

#

7025

# monitored_resources:

7026

# - type: library.googleapis.com/billing_branch

7027

# labels:

7028

# - key: cloud.googleapis.com/location

7029

# description: |

7030

# Predefined label to support billing location restriction.

7031

# - key: city

7032

# description: |

7033

# Custom label to define the city where the library branch is located

7034

# in.

7035

# - key: name

7036

# description: Custom label to define the name of the library branch.

7037

# metrics:

7038

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

7044

# - monitored_resource: library.googleapis.com/billing_branch

7045

# metrics:

7046

# - library.googleapis.com/book/borrowed_count

7047

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

7048

# There can be multiple consumer destinations per service, each one must have

7049

# a different monitored resource type. A metric can be used in at most

7050

# one consumer destination.

7051

{ # Configuration of a specific billing destination (Currently only support

7052

# bill against consumer project).

7053

"metrics": [ # Names of the metrics to report to this billing destination.

7054

# Each name must be defined in Service.metrics section.

7055

"A String",

7056

],

7057

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

7058

# Service.monitored_resources section.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

7063

# It serves similar purpose as [google.api.Service.types], except that

7064

# these types are not needed by user-defined APIs. Therefore, they will not

7065

# show up in the generated discovery doc. This field should only be used

7066

# to define system APIs in ESF.

7067

{ # A protocol buffer message type.

7068

"fields": [ # The list of fields.

7069

{ # A single field of a message type.

7070

"number": 42, # The field number.

7071

"name": "A String", # The field name.

7072

"kind": "A String", # The field type.

7073

"jsonName": "A String", # The field JSON name.

7074

"cardinality": "A String", # The field cardinality.

7075

"options": [ # The protocol buffer options.

7076

{ # A protocol buffer option, which can be attached to a message, field,

7077

# enumeration, etc.

7078

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7079

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7080

# For custom options, it should be the fully-qualified name. For example,

7081

# `"google.api.http"`.

7082

"value": { # The option's value packed in an Any message. If the value is a primitive,

7083

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7084

# should be used. If the value is an enum, it should be stored as an int32

7085

# value using the google.protobuf.Int32Value type.

7086

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

7091

"packed": True or False, # Whether to use alternative packed wire representation.

7092

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

7093

# types. The first type has index 1; zero means the type is not in the list.

7094

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

7095

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7096

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7097

],

7098

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

7099

"A String",

7100

],

7101

"name": "A String", # The fully qualified message name.

7102

"options": [ # The protocol buffer options.

7103

{ # A protocol buffer option, which can be attached to a message, field,

7104

# enumeration, etc.

7105

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7106

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7107

# For custom options, it should be the fully-qualified name. For example,

7108

# `"google.api.http"`.

7109

"value": { # The option's value packed in an Any message. If the value is a primitive,

7110

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7111

# should be used. If the value is an enum, it should be stored as an int32

7112

# value using the google.protobuf.Int32Value type.

7113

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"syntax": "A String", # The source syntax.

7118

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

7119

# protobuf element, like the file in which it is defined.

7120

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7121

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

},

},

],

"logging": { # Logging configuration of the service. # Logging configuration.

7126

#

7127

# The following example shows how to configure logs to be sent to the

7128

# producer and consumer projects. In the example, the `activity_history`

7129

# log is sent to both the producer and consumer projects, whereas the

7130

# `purchase_history` log is only sent to the producer project.

7131

#

7132

# monitored_resources:

7133

# - type: library.googleapis.com/branch

7134

# labels:

7135

# - key: /city

7136

# description: The city where the library branch is located in.

7137

# - key: /name

7138

# description: The name of the branch.

7139

# logs:

7140

# - name: activity_history

7141

# labels:

7142

# - key: /customer_id

7143

# - name: purchase_history

7144

# logging:

7145

# producer_destinations:

7146

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

7151

# - monitored_resource: library.googleapis.com/branch

7152

# logs:

7153

# - activity_history

7154

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

7155

# There can be multiple consumer destinations, each one must have a

7156

# different monitored resource type. A log can be used in at most

7157

# one consumer destination.

7158

{ # Configuration of a specific logging destination (the producer project

7159

# or the consumer project).

7160

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

7161

# Service.monitored_resources section.

7162

"logs": [ # Names of the logs to be sent to this destination. Each name must

7163

# be defined in the Service.logs section. If the log name is

7164

# not a domain scoped name, it will be automatically prefixed with

7165

# the service name followed by "/".

"A String",

],

},

],

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

7171

# There can be multiple producer destinations, each one must have a

7172

# different monitored resource type. A log can be used in at most

7173

# one producer destination.

7174

{ # Configuration of a specific logging destination (the producer project

7175

# or the consumer project).

7176

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

7177

# Service.monitored_resources section.

7178

"logs": [ # Names of the logs to be sent to this destination. Each name must

7179

# be defined in the Service.logs section. If the log name is

7180

# not a domain scoped name, it will be automatically prefixed with

7181

# the service name followed by "/".

"A String",

],

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

7188

# by the Service.monitoring and Service.logging configurations.

7189

{ # An object that describes the schema of a MonitoredResource object using a

7190

# type name and a set of labels. For example, the monitored resource

7191

# descriptor for Google Compute Engine VM instances has a type of

7192

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

7193

# `"zone"` to identify particular VM instances.

7194

#

7195

# Different APIs can support different monitored resource types. APIs generally

7196

# provide a `list` method that returns the monitored resource descriptors used

7197

# by the API.

7198

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

7199

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

7200

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

7201

# {type} is the value of the `type` field in this object and

7202

# {project_id} is a project ID that provides API-specific context for

7203

# accessing the type. APIs that do not use project information can use the

7204

# resource name format `"monitoredResourceDescriptors/{type}"`.

7205

"labels": [ # Required. A set of labels used to describe instances of this monitored

7206

# resource type. For example, an individual Google Cloud SQL database is

7207

# identified by values for the labels `"database_id"` and `"zone"`.

7208

{ # A description of a label.

7209

"valueType": "A String", # The type of data that can be assigned to the label.

7210

"key": "A String", # The label key.

7211

"description": "A String", # A human-readable description for the label.

7212

},

7213

],

7214

"type": "A String", # Required. The monitored resource type. For example, the type

7215

# `"cloudsql_database"` represents databases in Google Cloud SQL.

7216

# The maximum length of this value is 256 characters.

7217

"description": "A String", # Optional. A detailed description of the monitored resource type that might

7218

# be used in documentation.

7219

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

7220

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

7221

# without any article or other determiners. For example,

7222

# `"Google Cloud SQL Database"`.

7223

},

7224

],

7225

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

7226

#

7227

# The example below shows how to configure monitored resources and metrics

7228

# for monitoring. In the example, a monitored resource and two metrics are

7229

# defined. The `library.googleapis.com/book/returned_count` metric is sent

7230

# to both producer and consumer projects, whereas the

7231

# `library.googleapis.com/book/overdue_count` metric is only sent to the

7232

# consumer project.

7233

#

7234

# monitored_resources:

7235

# - type: library.googleapis.com/branch

7236

# labels:

7237

# - key: /city

7238

# description: The city where the library branch is located in.

7239

# - key: /name

7240

# description: The name of the branch.

7241

# metrics:

7242

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

7247

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

7252

# monitoring:

7253

# producer_destinations:

7254

# - monitored_resource: library.googleapis.com/branch

7255

# metrics:

7256

# - library.googleapis.com/book/returned_count

7257

# consumer_destinations:

7258

# - monitored_resource: library.googleapis.com/branch

7259

# metrics:

7260

# - library.googleapis.com/book/returned_count

7261

# - library.googleapis.com/book/overdue_count

7262

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

7263

# There can be multiple producer destinations. A monitored resouce type may

7264

# appear in multiple monitoring destinations if different aggregations are

7265

# needed for different sets of metrics associated with that monitored

7266

# resource type. A monitored resource and metric pair may only be used once

7267

# in the Monitoring configuration.

7268

{ # Configuration of a specific monitoring destination (the producer project

7269

# or the consumer project).

7270

"metrics": [ # Types of the metrics to report to this monitoring destination.

7271

# Each type must be defined in Service.metrics section.

7272

"A String",

7273

],

7274

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

7275

# Service.monitored_resources section.

7276

},

7277

],

7278

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

7279

# There can be multiple consumer destinations. A monitored resouce type may

7280

# appear in multiple monitoring destinations if different aggregations are

7281

# needed for different sets of metrics associated with that monitored

7282

# resource type. A monitored resource and metric pair may only be used once

7283

# in the Monitoring configuration.

7284

{ # Configuration of a specific monitoring destination (the producer project

7285

# or the consumer project).

7286

"metrics": [ # Types of the metrics to report to this monitoring destination.

7287

# Each type must be defined in Service.metrics section.

7288

"A String",

7289

],

7290

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

7291

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7292

},

7293

],

7294

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7295

"systemParameters": { # ### System parameter configuration # System parameter configuration.

7296

#

7297

# A system parameter is a special kind of parameter defined by the API

7298

# system, not by an individual API. It is typically mapped to an HTTP header

7299

# and/or a URL query parameter. This configuration specifies which methods

7300

# change the names of the system parameters.

7301

"rules": [ # Define system parameters.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7302

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7303

# The parameters defined here will override the default parameters

7304

# implemented by the system. If this field is missing from the service

7305

# config, default system parameters will be used. Default system parameters

7306

# and names is implementation-dependent.

7307

#

7308

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

7316

#

7317

#

7318

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

7323

# parameters:

7324

# - name: api_key

7325

# http_header: Api-Key1

7326

# - name: api_key

7327

# http_header: Api-Key2

7328

#

7329

# **NOTE:** All service configuration rules follow "last one wins" order.

7330

{ # Define a system parameter rule mapping system parameter definitions to

7331

# methods.

7332

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

7333

# For a given method call, only one of them should be used. If multiple

7334

# names are used the behavior is implementation-dependent.

7335

# If none of the specified names are present the behavior is

7336

# parameter-dependent.

7337

{ # Define a parameter's name and location. The parameter may be passed as either

7338

# an HTTP header or a URL query parameter, and if both are passed the behavior

7339

# is implementation-dependent.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7340

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

7341

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

7342

# sensitive.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7343

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

7344

# insensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7345

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7346

],

7347

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

7348

# methods in all APIs.

7349

#

7350

# Refer to selector for syntax details.

7351

},

7352

],

7353

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7354

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

7355

# usage.

7356

#

7357

# The metric based quota configuration works this way:

7358

# - The service configuration defines a set of metrics.

7359

# - For API calls, the quota.metric_rules maps methods to metrics with

7360

# corresponding costs.

7361

# - The quota.limits defines limits on the metrics, which will be used for

7362

# quota checks at runtime.

7363

#

7364

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

7370

# metric: library.googleapis.com/write_calls

7371

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

7377

# # except for the UpdateBook and DeleteBook methods. These two methods

7378

# # are mapped to the write_calls metric, with the UpdateBook method

7379

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

7384

# - selector: google.example.library.v1.LibraryService.UpdateBook

7385

# metric_costs:

7386

# library.googleapis.com/write_calls: 2

7387

# - selector: google.example.library.v1.LibraryService.DeleteBook

7388

# metric_costs:

7389

# library.googleapis.com/write_calls: 1

7390

#

7391

# Corresponding Metric definition:

7392

#

7393

# metrics:

7394

# - name: library.googleapis.com/read_calls

7395

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

7400

# display_name: Write requests

# metric_kind: DELTA

# value_type: INT64

#

"limits": [ # List of `QuotaLimit` definitions for the service.

7405

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

7406

# for a limit type. There can be at most one limit for a duration and limit

7407

# type combination defined within a `QuotaGroup`.

7408

"displayName": "A String", # User-visible display name for this limit.

7409

# Optional. If not set, the UI will provide a default display name based on

7410

# the quota configuration. This field can be used to override the default

7411

# display name generated from the configuration.

7412

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

7413

# duration. Client application developers can override the default limit up

7414

# to this maximum. If specified, this value cannot be set to a value less

7415

# than the default limit. If not specified, it is set to the default limit.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7416

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7417

# To allow clients to apply overrides with no upper bound, set this to -1,

7418

# indicating unlimited maximum quota.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7419

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7420

# Used by group-based quotas only.

7421

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7422

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7423

# Used by group-based quotas only.

7424

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

7425

# The free tier is the number of tokens that will be subtracted from the

7426

# billed amount when billing is enabled.

7427

# This field can only be set on a limit with duration "1d", in a billable

7428

# group; it is invalid on any other limit. If this field is not set, it

7429

# defaults to 0, indicating that there is no free tier for this service.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7430

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7431

# Used by group-based quotas only.

7432

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

7433

# Metric.unit. The supported unit kinds are determined by the quota

7434

# backend system.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7435

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7436

# Here are some examples:

7437

# * "1/min/{project}" for quota per minute per project.

7438

#

7439

# Note: the order of unit components is insignificant.

7440

# The "1" at the beginning is required to follow the metric unit syntax.

7441

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

7442

# duration. This is the number of tokens assigned when a client

7443

# application developer activates the service for his/her project.

7444

#

7445

# Specifying a value of 0 will block all requests. This can be used if you

7446

# are provisioning quota to selected consumers and blocking others.

7447

# Similarly, a value of -1 will indicate an unlimited quota. No other

7448

# negative values are allowed.

7449

#

7450

# Used by group-based quotas only.

7451

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

7452

# integer value that is the maximum number of requests allowed for the

7453

# specified unit. Currently only STANDARD is supported.

7454

"a_key": "A String",

7455

},

7456

"name": "A String", # Name of the quota limit.

7457

#

7458

# The name must be provided, and it must be unique within the service. The

7459

# name can only include alphanumeric characters as well as '-'.

7460

#

7461

# The maximum length of the limit name is 64 characters.

7462

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

7463

# the same metric will be checked together during runtime. The metric must be

7464

# defined within the service config.

7465

"description": "A String", # Optional. User-visible, extended description for this quota limit.

7466

# Should be used only when more context is needed to understand this limit

7467

# than provided by the limit's display name (see: `display_name`).

7468

},

7469

],

7470

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

7471

# or more metrics.

7472

{ # Bind API methods to metrics. Binding a method to a metric causes that

7473

# metric's configured quota behaviors to apply to the method call.

7474

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

7475

# cost applied to each metric.

7476

#

7477

# The key of the map is the metric name, and the values are the amount

7478

# increased for the metric against which the quota limits are defined.

7479

# The value must not be negative.

7480

"a_key": "A String",

7481

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7482

"selector": "A String", # Selects the methods to which this rule applies.

7483

#

7484

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7485

},

7486

],

7487

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7488

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7489

#

7490

# Example:

7491

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

7497

# - google.rpc.context.OriginContext

7498

#

7499

# The above specifies that all methods in the API request

7500

# `google.rpc.context.ProjectContext` and

7501

# `google.rpc.context.OriginContext`.

7502

#

7503

# Available context types are defined in package

7504

# `google.rpc.context`.

7505

#

7506

# This also provides mechanism to whitelist any protobuf message extension that

7507

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

7508

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

7509

# 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"

7517

# allowed_request_extensions:

7518

# - google.foo.v1.NewExtension

7519

# allowed_response_extensions:

7520

# - google.foo.v1.NewExtension

7521

#

7522

# You can also specify extension ID instead of fully qualified extension name

7523

# here.

7524

"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]

7525

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7526

# **NOTE:** All service configuration rules follow "last one wins" order.

7527

{ # A context rule provides information about the context for an individual API

7528

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7529

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7530

# side channel from client to backend.

7531

"A String",

7532

],

7533

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7534

# side channel from backend to client.

7535

"A String",

7536

],

7537

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7538

#

7539

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7540

"requested": [ # A list of full type names of requested contexts.

7541

"A String",

7542

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7543

"provided": [ # A list of full type names of provided contexts.

7544

"A String",

7545

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7546

},

7547

],

7548

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7549

"producerProjectId": "A String", # The Google project that owns this service.

7550

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

7551

"rules": [ # A list of API backend rules that apply to individual API methods.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7552

#

7553

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7554

{ # A backend rule provides configuration for an individual API element.

7555

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

7556

# operation. The default is no deadline.

7557

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

7558

# value lower than this will be rejected.

7559

"address": "A String", # The address of the API backend.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7560

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7561

# The scheme is used to determine the backend protocol and security.

7562

# The following schemes are accepted:

7563

#

7564

# 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

7571

# may cause constrasting behaviors across platforms.

7572

#

7573

# If the port is unspecified, the default is:

7574

# - 80 for schemes without TLS

7575

# - 443 for schemes with TLS

7576

#

7577

# For HTTP backends, use protocol

7578

# to specify the protocol version.

7579

"pathTranslation": "A String",

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7580

"selector": "A String", # Selects the methods to which this rule applies.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7581

#

7582

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7583

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

7584

# This ID token will be added in the HTTP "authorization" header, and sent

7585

# to the backend.

7586

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

7587

# original "Authorization" HTTP header will be preserved. If the header is

7588

# used to carry the original token and is expected by the backend, this

7589

# field must be set to true to preserve the header.

7590

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

7591

# varies based on the request protocol and deployment environment.

7592

"protocol": "A String", # The protocol used for sending a request to the backend.

7593

# The supported values are "http/1.1" and "h2".

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7594

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7595

# The default value is inferred from the scheme in the

7596

# address field:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7597

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7603

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7604

# For secure HTTP backends (https://) that support HTTP/2, set this field

7605

# to "h2" for improved performance.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7606

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7607

# Configuring this field to non-default values is only supported for secure

7608

# HTTP backends. This field will be ignored for all other backends.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7609

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7610

# See

7611

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

7612

# for more details on the supported values.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7613

},

7614

],

7615

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7616

},

7617

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7618

"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>

7624

<pre>Retrieves the next page of results.

7625

7626

Args:

7627

previous_request: The request for the previous page. (required)

7628

previous_response: The response from the request for the previous page. (required)

7629

7630

Returns:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7631

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]

7632

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]

7637

<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]

7638

<pre>Creates a new service configuration (version) for a managed service based

7639

on

7640

user-supplied configuration source files (for example: OpenAPI

7641

Specification). This method stores the source configurations as well as the

7642

generated service configuration. To rollout the service configuration to

7643

other services,

7644

please call CreateServiceRollout.

7645

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7646

Only the 100 most recent configuration sources and ones referenced by

7647

existing service configurtions are kept for each service. The rest will be

7648

deleted eventually.

7649

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7650

Operation<response: SubmitConfigSourceResponse>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7651

7652

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7653

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]

7654

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7655

body: object, The request body.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7656

The object takes the form of:

7657

7658

{ # Request message for SubmitConfigSource method.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7659

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7660

# `google.api.Service` configuration based on the `ConfigSource` provided,

7661

# but the generated config and the sources will NOT be persisted.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7662

"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]

7663

# defined by `google.api.Service`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7664

"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]

7665

# by the client for tracking purpose. If empty, the server may choose to

7666

# generate one instead.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7667

"files": [ # Set of source configuration files that are used to generate a service

7668

# configuration (`google.api.Service`).

7669

{ # Generic specification of a source configuration file

7670

"filePath": "A String", # The file name of the configuration file (full or relative path).

7671

"fileType": "A String", # The type of configuration file this represents.

7672

"fileContents": "A String", # The bytes that constitute the file.

7673

},

7674

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

7685

7686

{ # This resource represents a long-running operation that is the result of a

7687

# network API call.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame^]

7688

"error": { # The `Status` type defines a logical error model that is suitable for # The error result of the operation in case of failure or cancellation.

7689

# different programming environments, including REST APIs and RPC APIs. It is

7690

# used by [gRPC](https://github.com/grpc). Each `Status` message contains

7691

# three pieces of data: error code, error message, and error details.

7692

#

7693

# You can find out more about this error model and how to work with it in the

7694

# [API Design Guide](https://cloud.google.com/apis/design/errors).

7695

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

7696

"message": "A String", # A developer-facing error message, which should be in English. Any

7697

# user-facing error message should be localized and sent in the

7698

# google.rpc.Status.details field, or localized by the client.

7699

"details": [ # A list of messages that carry the error details. There is a common set of

7700

# message types for APIs to use.

7701

{

7702

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

],

},

"name": "A String", # The server-assigned name, which is only unique within the same service that

7707

# originally returns it. If you use the default HTTP mapping, the

7708

# `name` should be a resource name ending with `operations/{unique_id}`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7709

"metadata": { # Service-specific metadata associated with the operation. It typically

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7710

# contains progress information and common metadata such as create time.

7711

# Some services might not provide such metadata. Any method that returns a

7712

# long-running operation should document the metadata type, if any.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7713

"a_key": "", # Properties of the object. Contains field @type with type URL.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7714

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7715

"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]

7716

# If `true`, the operation is completed, and either `error` or `response` is

7717

# available.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7718

"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]

7719

# method returns no data on success, such as `Delete`, the response is

7720

# `google.protobuf.Empty`. If the original method is standard

7721

# `Get`/`Create`/`Update`, the response should be the resource. For other

7722

# methods, the response should have the type `XxxResponse`, where `Xxx`

7723

# is the original method name. For example, if the original method name

7724

# is `TakeSnapshot()`, the inferred response type is

7725

# `TakeSnapshotResponse`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7726

"a_key": "", # Properties of the object. Contains field @type with type URL.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7727

},

Jon Wayne Parrott