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-07-22 17:02:09 -0700

[diff] [blame^]

84

<code><a href="#list">list(serviceName, pageSize=None, pageToken=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

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

134

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

135

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

136

# should be listed here by name. Example:

137

#

138

# enums:

139

# - name: google.someapi.v1.SomeEnum

140

{ # Enum type definition.

141

"options": [ # Protocol buffer options.

142

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

143

# enumeration, etc.

Bu Sun Kim

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

[diff] [blame]

144

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

145

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

146

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

147

# value using the google.protobuf.Int32Value type.

148

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

149

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

150

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

151

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

152

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

153

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

154

},

155

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

156

"enumvalue": [ # Enum value definitions.

157

{ # Enum value definition.

158

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

159

"options": [ # Protocol buffer options.

160

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

161

# enumeration, etc.

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

},

168

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

169

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

170

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

171

# `"google.api.http"`.

172

},

173

],

174

"number": 42, # Enum value number.

175

},

176

],

Bu Sun Kim

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

[diff] [blame]

177

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

178

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

179

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

180

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

181

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

182

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

183

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

184

},

185

],

186

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

187

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

188

#

189

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

190

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

191

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

192

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

193

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

194

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

195

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

196

#

197

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

198

# The following schemes are accepted:

199

#

200

# 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

207

# may cause constrasting behaviors across platforms.

208

#

209

# If the port is unspecified, the default is:

210

# - 80 for schemes without TLS

211

# - 443 for schemes with TLS

212

#

213

# For HTTP backends, use protocol

214

# to specify the protocol version.

215

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

216

# value lower than this will be rejected.

217

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

218

#

219

# Refer to selector for syntax details.

220

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

221

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

222

#

223

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

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

233

# to "h2" for improved performance.

234

#

235

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

236

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

237

#

238

# See

239

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

240

# for more details on the supported values.

241

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

242

# operation. The default is no deadline.

243

"pathTranslation": "A String",

244

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

245

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

246

# to the backend.

247

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

248

# varies based on the request protocol and deployment environment.

},

],

},

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

253

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

254

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

255

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

256

# to define system APIs in ESF.

257

{ # A protocol buffer message type.

258

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

259

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

260

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

261

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

262

},

263

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

264

"A String",

265

],

266

"fields": [ # The list of fields.

267

{ # A single field of a message type.

268

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

269

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

270

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

271

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

272

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

273

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

274

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

275

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

276

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

277

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

278

"options": [ # The protocol buffer options.

Bu Sun Kim

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

[diff] [blame]

279

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

280

# enumeration, etc.

Bu Sun Kim

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

[diff] [blame]

281

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

282

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

283

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

284

# value using the google.protobuf.Int32Value type.

285

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

286

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

287

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

288

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

289

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

290

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

291

},

292

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

293

"number": 42, # The field number.

Bu Sun Kim

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

[diff] [blame]

294

},

295

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

296

"options": [ # The protocol buffer options.

Bu Sun Kim

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

[diff] [blame]

297

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

298

# enumeration, etc.

299

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

300

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

301

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

302

# value using the google.protobuf.Int32Value type.

303

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

304

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

305

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

306

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

307

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

308

# `"google.api.http"`.

Bu Sun Kim

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

[diff] [blame]

309

},

310

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

311

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

312

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

Bu Sun Kim

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

[diff] [blame]

313

},

314

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

315

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

316

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

317

# typically goes through DNS verification to make sure the owner

318

# of the service also owns the DNS name.

319

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

320

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

321

{

322

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

Bu Sun Kim

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

[diff] [blame]

323

},

Jon Wayne Parrott

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

[diff] [blame]

324

],

325

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

326

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

327

#

328

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

329

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

330

# the monitored resources need at least one label key

331

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

332

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

333

# recommended so they can be evolved independently:

334

#

335

#

336

# monitored_resources:

337

# - type: library.googleapis.com/billing_branch

338

# labels:

339

# - key: cloud.googleapis.com/location

340

# description: |

341

# Predefined label to support billing location restriction.

342

# - key: city

343

# description: |

344

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

345

# in.

346

# - key: name

347

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

348

# metrics:

349

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

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

355

# - monitored_resource: library.googleapis.com/billing_branch

356

# metrics:

357

# - library.googleapis.com/book/borrowed_count

358

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

359

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

360

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

361

# one consumer destination.

362

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

363

# bill against consumer project).

364

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

365

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

366

"A String",

367

],

368

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

369

# Service.monitored_resources section.

},

],

},

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

374

#

375

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

376

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

377

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

378

# to both producer and consumer projects, whereas the

379

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

380

# consumer project.

381

#

382

# monitored_resources:

383

# - type: library.googleapis.com/Branch

384

# display_name: "Library Branch"

385

# description: "A branch of a library."

386

# launch_stage: GA

387

# labels:

388

# - key: resource_container

389

# description: "The Cloud container (ie. project id) for the Branch."

390

# - key: location

391

# description: "The location of the library branch."

392

# - key: branch_id

393

# description: "The id of the branch."

394

# metrics:

395

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

396

# display_name: "Books Returned"

397

# description: "The count of books that have been returned."

# launch_stage: GA

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

405

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

406

# display_name: "Books Overdue"

407

# description: "The current number of overdue books."

# launch_stage: GA

# metric_kind: GAUGE

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

415

# monitoring:

416

# producer_destinations:

417

# - monitored_resource: library.googleapis.com/Branch

418

# metrics:

419

# - library.googleapis.com/book/returned_count

420

# consumer_destinations:

421

# - monitored_resource: library.googleapis.com/Branch

422

# metrics:

423

# - library.googleapis.com/book/returned_count

424

# - library.googleapis.com/book/num_overdue

425

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

426

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

427

# appear in multiple monitoring destinations if different aggregations are

428

# needed for different sets of metrics associated with that monitored

429

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

430

# in the Monitoring configuration.

431

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

432

# or the consumer project).

433

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

434

# Service.monitored_resources section.

435

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

436

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

"A String",

],

},

],

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

442

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

443

# appear in multiple monitoring destinations if different aggregations are

444

# needed for different sets of metrics associated with that monitored

445

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

446

# in the Monitoring configuration.

447

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

448

# or the consumer project).

449

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

450

# Service.monitored_resources section.

451

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

452

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

"A String",

],

},

],

},

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

459

#

460

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

461

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

462

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

463

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

464

#

465

# monitored_resources:

466

# - type: library.googleapis.com/branch

467

# labels:

468

# - key: /city

469

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

470

# - key: /name

471

# description: The name of the branch.

472

# logs:

473

# - name: activity_history

474

# labels:

475

# - key: /customer_id

476

# - name: purchase_history

477

# logging:

478

# producer_destinations:

479

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

484

# - monitored_resource: library.googleapis.com/branch

485

# logs:

486

# - activity_history

487

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

488

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

489

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

490

# one producer destination.

491

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

492

# or the consumer project).

493

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

494

# Service.monitored_resources section.

495

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

496

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

497

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

498

# the service name followed by "/".

"A String",

],

},

],

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

504

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

505

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

506

# one consumer destination.

507

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

508

# or the consumer project).

509

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

510

# Service.monitored_resources section.

511

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

512

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

513

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

514

# the service name followed by "/".

"A String",

],

},

],

},

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

521

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

522

# monitoring, etc.

523

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

524

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

525

},

Bu Sun Kim

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

[diff] [blame]

526

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

527

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

528

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

529

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

530

"A String",

531

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

532

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

533

#

534

#

535

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

536

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

541

# display_name: "Cloud XXX Service Agent"

542

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

543

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

544

#

545

# An example name would be:

546

# `projects/123456789`

547

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

548

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

549

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

550

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

551

},

Bu Sun Kim

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

[diff] [blame]

552

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

553

#

554

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

555

{ # Usage configuration rules for the service.

556

#

557

# NOTE: Under development.

558

#

559

#

560

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

561

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

562

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

563

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

564

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

565

# allow/disallow unregistered calls.

566

#

567

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

573

#

574

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

#

# usage:

# rules:

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

579

# allow_unregistered_calls: true

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

580

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

581

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

582

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

583

# methods, such as service health check methods.

Bu Sun Kim

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

[diff] [blame]

584

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

585

# methods in all APIs.

586

#

587

# Refer to selector for syntax details.

588

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

589

# that don't identify any user or application.

Bu Sun Kim

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

[diff] [blame]

590

},

591

],

592

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

593

# service producer.

594

#

595

# Google Service Management currently only supports

596

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

597

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

598

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

599

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

Bu Sun Kim

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

[diff] [blame]

600

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

601

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

602

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

603

# automatically included. Messages which are not referenced but

604

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

605

# should be listed here by name. Example:

606

#

607

# types:

608

# - name: google.protobuf.Int32

609

{ # A protocol buffer message type.

610

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

611

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

612

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

613

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

614

},

615

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

Bu Sun Kim

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

[diff] [blame]

616

"A String",

617

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

618

"fields": [ # The list of fields.

619

{ # A single field of a message type.

620

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

621

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

622

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

623

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

624

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

625

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

626

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

627

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

628

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

629

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

630

"options": [ # The protocol buffer options.

631

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

632

# enumeration, etc.

633

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

634

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

635

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

636

# value using the google.protobuf.Int32Value type.

637

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

638

},

639

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

640

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

641

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

642

# `"google.api.http"`.

643

},

644

],

645

"number": 42, # The field number.

646

},

Bu Sun Kim

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

[diff] [blame]

647

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

648

"options": [ # The protocol buffer options.

649

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

650

# enumeration, etc.

651

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

652

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

653

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

654

# value using the google.protobuf.Int32Value type.

655

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

656

},

657

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

658

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

659

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

660

# `"google.api.http"`.

661

},

662

],

663

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

664

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

Bu Sun Kim

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

[diff] [blame]

665

},

666

],

Bu Sun Kim

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

[diff] [blame]

667

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

668

# HttpRule, each specifying the mapping of an RPC method

669

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

670

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

671

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

672

# left encoded.

673

#

674

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

675

# segment matches.

Bu Sun Kim

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

[diff] [blame]

676

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

677

#

678

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

Bu Sun Kim

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

[diff] [blame]

679

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

680

#

Bu Sun Kim

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

[diff] [blame]

681

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

682

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

683

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

684

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

685

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

686

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

687

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

688

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

689

#

Bu Sun Kim

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

[diff] [blame]

690

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

691

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

692

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

693

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

694

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

695

#

696

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

697

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

698

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

699

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

700

# the URL path.

701

#

702

# Example:

Jon Wayne Parrott

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

[diff] [blame]

703

#

704

# service Messaging {

705

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

706

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

707

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

Bu Sun Kim

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

[diff] [blame]

708

# };

Jon Wayne Parrott

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

[diff] [blame]

709

# }

710

# }

711

# message GetMessageRequest {

Bu Sun Kim

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

[diff] [blame]

712

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

Jon Wayne Parrott

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

[diff] [blame]

713

# }

714

# message Message {

Bu Sun Kim

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

[diff] [blame]

715

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

Jon Wayne Parrott

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

[diff] [blame]

716

# }

717

#

Bu Sun Kim

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

[diff] [blame]

718

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

Jon Wayne Parrott

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

[diff] [blame]

719

#

Bu Sun Kim

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

[diff] [blame]

720

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

721

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

Bu Sun Kim

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

[diff] [blame]

722

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

Jon Wayne Parrott

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

[diff] [blame]

723

#

Bu Sun Kim

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

[diff] [blame]

724

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

725

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

726

# For example:

Jon Wayne Parrott

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

[diff] [blame]

727

#

Sai Cheemalapati

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

[diff] [blame]

728

# service Messaging {

729

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

730

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

731

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

Bu Sun Kim

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

[diff] [blame]

732

# };

Sai Cheemalapati

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

[diff] [blame]

733

# }

734

# }

Jon Wayne Parrott

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

[diff] [blame]

735

# message GetMessageRequest {

736

# message SubMessage {

737

# string subfield = 1;

738

# }

Bu Sun Kim

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

[diff] [blame]

739

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

740

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

741

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

Jon Wayne Parrott

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

[diff] [blame]

742

# }

743

#

Jon Wayne Parrott

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

[diff] [blame]

744

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

745

#

Bu Sun Kim

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

[diff] [blame]

746

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

747

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

Dan O'Meara

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

[diff] [blame]

748

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

Bu Sun Kim

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

[diff] [blame]

749

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

750

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

751

#

Bu Sun Kim

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

[diff] [blame]

752

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

753

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

754

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

755

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

756

# message is mapped to a separate parameter, such as

Dan O'Meara

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

[diff] [blame]

757

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

Jon Wayne Parrott

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

[diff] [blame]

758

#

Bu Sun Kim

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

[diff] [blame]

759

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

Jon Wayne Parrott

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

[diff] [blame]

760

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

761

# message resource collection:

762

#

Jon Wayne Parrott

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

[diff] [blame]

763

# service Messaging {

764

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

765

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

766

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

767

# body: "message"

Jon Wayne Parrott

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

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

772

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

773

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

774

# }

775

#

Jon Wayne Parrott

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

[diff] [blame]

776

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

777

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

778

# protos JSON encoding:

779

#

Bu Sun Kim

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

[diff] [blame]

780

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

781

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

Bu Sun Kim

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

[diff] [blame]

782

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

783

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

Jon Wayne Parrott

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

[diff] [blame]

784

#

785

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

786

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

787

# request body. This enables the following alternative definition of

788

# the update method:

789

#

Jon Wayne Parrott

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

[diff] [blame]

790

# service Messaging {

791

# rpc UpdateMessage(Message) returns (Message) {

792

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

793

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

794

# body: "*"

Jon Wayne Parrott

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

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

800

# string text = 2;

801

# }

802

#

Jon Wayne Parrott

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

[diff] [blame]

803

#

804

# The following HTTP JSON to RPC mapping is enabled:

805

#

Bu Sun Kim

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

[diff] [blame]

806

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

807

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

Bu Sun Kim

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

[diff] [blame]

808

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

809

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

Jon Wayne Parrott

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

[diff] [blame]

810

#

811

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

812

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

813

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

Jon Wayne Parrott

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

[diff] [blame]

814

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

Bu Sun Kim

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

[diff] [blame]

815

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

Jon Wayne Parrott

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

[diff] [blame]

816

#

817

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

818

# the `additional_bindings` option. Example:

819

#

Jon Wayne Parrott

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

[diff] [blame]

820

# service Messaging {

821

# rpc GetMessage(GetMessageRequest) returns (Message) {

822

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

823

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

Jon Wayne Parrott

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

[diff] [blame]

824

# additional_bindings {

Bu Sun Kim

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

[diff] [blame]

825

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

Jon Wayne Parrott

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

[diff] [blame]

826

# }

827

# };

Jon Wayne Parrott

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

[diff] [blame]

828

# }

Jon Wayne Parrott

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

[diff] [blame]

829

# }

830

# message GetMessageRequest {

831

# string message_id = 1;

832

# string user_id = 2;

833

# }

834

#

Bu Sun Kim

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

[diff] [blame]

835

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

Jon Wayne Parrott

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

[diff] [blame]

836

#

Bu Sun Kim

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

[diff] [blame]

837

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

838

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

Bu Sun Kim

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

[diff] [blame]

839

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

840

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

841

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

842

#

Bu Sun Kim

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

[diff] [blame]

843

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

844

#

Bu Sun Kim

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

[diff] [blame]

845

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

846

# message) are classified into three categories:

847

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

848

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

849

# request body.

850

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

851

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

852

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

853

# name.

Bu Sun Kim

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

[diff] [blame]

854

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

855

# are passed via URL path and HTTP request body.

856

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

857

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

Jon Wayne Parrott

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

[diff] [blame]

858

#

Bu Sun Kim

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

[diff] [blame]

859

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

860

#

Bu Sun Kim

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

[diff] [blame]

861

# Template = "/" Segments [ Verb ] ;

862

# Segments = Segment { "/" Segment } ;

863

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

864

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

865

# FieldPath = IDENT { "." IDENT } ;

866

# Verb = ":" LITERAL ;

Jon Wayne Parrott

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

[diff] [blame]

867

#

Bu Sun Kim

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

[diff] [blame]

868

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

869

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

870

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

871

#

Bu Sun Kim

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

[diff] [blame]

872

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

873

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

Jon Wayne Parrott

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

[diff] [blame]

874

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

875

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

876

#

Bu Sun Kim

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

[diff] [blame]

877

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

878

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

879

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

880

#

Bu Sun Kim

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

[diff] [blame]

881

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

882

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

883

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

884

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

885

# [Discovery

886

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

887

# `{var}`.

888

#

Bu Sun Kim

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

[diff] [blame]

889

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

890

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

891

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

Bu Sun Kim

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

[diff] [blame]

892

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

893

# unchanged. Such variables show up in the

894

# [Discovery

895

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

896

# `{+var}`.

897

#

898

# ## Using gRPC API Service Configuration

899

#

900

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

901

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

902

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

903

# proto message.

904

#

905

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

906

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

907

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

908

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

909

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

910

# specified in the service config will override any matching transcoding

911

# configuration in the proto.

#

# Example:

#

# http:

# rules:

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

918

# - selector: example.v1.Messaging.GetMessage

919

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

#

# ## Special notes

#

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

924

# proto to JSON conversion must follow the [proto3

925

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

926

#

927

# While the single segment variable follows the semantics of

928

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

929

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

930

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

931

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

932

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

933

# for multi segment variables.

934

#

935

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

936

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

937

#

Bu Sun Kim

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

[diff] [blame]

938

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

939

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

940

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

941

#

942

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

943

# no client library can support such complicated mapping.

944

#

945

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

946

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

947

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

948

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

Bu Sun Kim

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

[diff] [blame]

949

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

950

#

951

# Refer to selector for syntax details.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

952

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

953

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

954

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

955

# as the HTTP response body.

956

#

957

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

958

# message type.

959

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

960

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

961

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

962

#

963

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

964

# message type.

965

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

966

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

967

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

968

# the nesting may only be one level deep).

969

# Object with schema name: HttpRule

970

],

Bu Sun Kim

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

[diff] [blame]

971

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

972

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

973

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

974

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

975

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

976

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

977

},

Bu Sun Kim

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

[diff] [blame]

978

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

979

# half-duplex streaming method.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

980

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

Bu Sun Kim

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

[diff] [blame]

981

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

982

# resources.

Bu Sun Kim

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

[diff] [blame]

983

},

984

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

985

},

986

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

987

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

Bu Sun Kim

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

[diff] [blame]

988

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

989

# - name: library.googleapis.com/activity_history

990

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

991

# display_name: Activity

992

# labels:

993

# - key: /customer_id

994

# description: Identifier of a library customer

995

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

996

# the documentation and can contain details.

997

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

998

# Runtime requests that contain labels not specified here are

999

# considered invalid.

Bu Sun Kim

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

[diff] [blame]

1000

{ # A description of a label.

1001

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

Bu Sun Kim

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

[diff] [blame]

1002

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

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1003

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

Bu Sun Kim

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

[diff] [blame]

1004

},

1005

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1006

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

1007

# the user interface and should be concise.

1008

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

1009

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

1010

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

1011

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

Bu Sun Kim

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

[diff] [blame]

1012

},

1013

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1014

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

1015

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

1016

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

1017

# existing data unusable.

1018

#

1019

# The following are specific rules for service defined Monitoring metric

1020

# descriptors:

1021

#

1022

# * `type`, `metric_kind`, `value_type`, `description`, and `display_name`

1023

# fields are all required. The `unit` field must be specified

1024

# if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.

1025

# * Maximum of default 500 metric descriptors per service is allowed.

1026

# * Maximum of default 10 labels per metric descriptor is allowed.

1027

#

1028

# The default maximum limit can be overridden. Please follow

1029

# https://cloud.google.com/monitoring/quotas

1030

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

1031

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

1032

# defines the representation of the stored metric values.

1033

#

1034

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

1035

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

1036

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

1037

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

1038

# matter how it may be displayed..

1039

#

1040

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

1041

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

1042

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

1043

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

1044

#

1045

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

1046

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

1047

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

1048

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

1049

#

1050

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

1051

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

1052

#

1053

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

# * `1` dimensionless

1062

#

1063

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

1072

# * `Y` yotta (10^24)

1073

#

1074

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

1075

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

1076

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

1077

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

1078

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

1079

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

1080

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

1081

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

1092

#

1093

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

1094

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

1095

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

1096

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

1097

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

1098

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

1099

#

1100

# The grammar for a unit is as follows:

1101

#

1102

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

1103

#

1104

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

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1114

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

1115

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

1116

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

1117

# containing `{` or `}`.

1118

# * `1` represents a unitary [dimensionless

1119

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

1120

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

1121

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

1122

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

1123

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

1124

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

1125

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

1126

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

1127

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

1128

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

1129

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

1130

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

1131

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

1132

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

1133

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

1134

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

1135

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

1136

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

1137

# series, which is identified partially by

1138

# a metric type and a MonitoredResourceDescriptor, that is associated

1139

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

1140

# resource types listed here.

1141

"A String",

1142

],

1143

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

1144

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

1145

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

1146

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

1147

# a smaller sampling period.

1148

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

1149

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

1150

# data loss due to errors.

1151

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

Bu Sun Kim

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

[diff] [blame]

1152

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1153

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

1154

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

1155

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

1156

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

1157

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

1158

# URL-encoded.

1159

#

1160

# All service defined metrics must be prefixed with the service name, in the

1161

# format of `{service name}/{relative metric name}`, such as

1162

# `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric

1163

# name must follow:

1164

#

1165

# * Only upper and lower-case letters, digits, '/' and underscores '_' are

1166

# allowed.

1167

# * The maximum number of characters allowed for the relative_metric_name is

1168

# 100.

1169

#

1170

# All user-defined metric types have the DNS name

1171

# `custom.googleapis.com`, `external.googleapis.com`, or

1172

# `logging.googleapis.com/user/`.

1173

#

1174

# Metric types should use a natural hierarchical grouping. For example:

1175

#

1176

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

1177

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

1178

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

1179

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

1180

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

1181

# instance of this metric type.

1182

#

1183

# The label key name must follow:

1184

#

1185

# * Only upper and lower-case letters, digits and underscores (_) are

1186

# allowed.

1187

# * Label name must start with a letter or digit.

1188

# * The maximum length of a label name is 100 characters.

1189

#

1190

# For example, the

1191

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

1192

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

1193

# you can look at latencies for successful responses or just

1194

# for responses that failed.

1195

{ # A description of a label.

1196

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

1197

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

1198

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

1199

},

1200

],

1201

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

1202

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

1203

},

1204

],

1205

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

Bu Sun Kim

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

[diff] [blame]

1206

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1207

# Example:

1208

# <pre><code>documentation:

1209

# summary: >

1210

# The Google Calendar API gives access

1211

# to most calendar features.

1212

# pages:

1213

# - name: Overview

1214

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

1215

# - name: Tutorial

1216

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

1217

# subpages;

1218

# - name: Java

1219

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

1220

# rules:

1221

# - selector: google.calendar.Calendar.Get

1222

# description: >

1223

# ...

1224

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1229

# standard markdown features, definition lists, tables and fenced

1230

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

1231

# interpreted relative to the section nesting of the context where

1232

# a documentation fragment is embedded.

1233

#

1234

# Documentation from the IDL is merged with documentation defined

1235

# via the config at normalization time, where documentation provided

1236

# by config rules overrides IDL provided.

1237

#

1238

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

1239

# in documentation text.

1240

#

1241

# In order to reference a proto element, the following

1242

# notation can be used:

1243

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

1244

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

1245

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

1246

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

1247

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

1248

#

1249

# A few directives are available in documentation. Note that

1250

# directives must appear on a single line to be properly

1251

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

1252

# an external source:

1253

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

1254

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

1255

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

1256

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

1257

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

1258

# The directive `suppress_warning` does not directly affect documentation

1259

# and is documented together with service config validation.

1260

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

1261

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

1262

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

1263

# urls are relative to.

1264

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

1265

# <pre><code>documentation:

1266

# summary: ...

1267

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

1268

# </code></pre>

1269

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

1270

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1275

# </code></pre>

1276

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

1277

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

1278

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

Bu Sun Kim

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

[diff] [blame]

1279

#

1280

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

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1281

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

1282

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

1283

# an element is marked as `deprecated`.

1284

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

1285

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

1286

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

1287

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

1288

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

1289

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

1290

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

Bu Sun Kim

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

[diff] [blame]

1291

},

1292

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1293

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

1294

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

1295

# nested documentation set structure.

1296

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

1297

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

1298

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

1299

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

1300

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

1301

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

1302

# documentation. For example:

1303

# <pre><code>pages:

1304

# - name: Tutorial

1305

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

1306

# subpages:

1307

# - name: Java

1308

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

1309

# </code></pre>

1310

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

1311

# `Java`.

1312

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

1313

# honored in the generated docset.

1314

# Object with schema name: Page

],

},

],

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

1319

# plain text.

Bu Sun Kim

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

[diff] [blame]

1320

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1321

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

1322

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

1323

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

1324

#

1325

# The latest config version is `3`.

Bu Sun Kim

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

[diff] [blame]

1326

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

1327

# usage.

1328

#

1329

# The metric based quota configuration works this way:

1330

# - The service configuration defines a set of metrics.

1331

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

1332

# corresponding costs.

1333

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

1334

# quota checks at runtime.

1335

#

1336

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

1342

# metric: library.googleapis.com/write_calls

1343

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

# values:

# STANDARD: 10000

#

#

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

1349

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

1350

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

1351

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1356

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

1357

# metric_costs:

1358

# library.googleapis.com/write_calls: 2

1359

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

1360

# metric_costs:

1361

# library.googleapis.com/write_calls: 1

1362

#

1363

# Corresponding Metric definition:

1364

#

1365

# metrics:

1366

# - name: library.googleapis.com/read_calls

1367

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1372

# display_name: Write requests

1373

# metric_kind: DELTA

1374

# value_type: INT64

1375

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1376

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

1377

# or more metrics.

1378

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

1379

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

1380

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

1381

#

1382

# Refer to selector for syntax details.

1383

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

1384

# cost applied to each metric.

1385

#

1386

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

1387

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

1388

# The value must not be negative.

"a_key": "A String",

},

},

],

Bu Sun Kim

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

[diff] [blame]

1393

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

1394

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

1395

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

1396

# type combination defined within a `QuotaGroup`.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1397

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

1398

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

1399

# specified unit. Currently only STANDARD is supported.

1400

"a_key": "A String",

1401

},

Bu Sun Kim

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

[diff] [blame]

1402

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

1403

#

Bu Sun Kim

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

[diff] [blame]

1404

# Used by group-based quotas only.

1405

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

1406

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

1407

# billed amount when billing is enabled.

1408

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

1409

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

1410

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

1411

#

Bu Sun Kim

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

[diff] [blame]

1412

# Used by group-based quotas only.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1413

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

1414

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

1415

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

1416

# display name generated from the configuration.

1417

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

1418

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

1419

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

Bu Sun Kim

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

[diff] [blame]

1420

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

1421

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

1422

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

1423

#

1424

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

1425

# are provisioning quota to selected consumers and blocking others.

1426

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

1427

# negative values are allowed.

1428

#

1429

# Used by group-based quotas only.

Bu Sun Kim

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

[diff] [blame]

1430

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

1431

#

1432

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

1433

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

1434

#

1435

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

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1436

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

1437

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

1438

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

1439

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

1440

#

1441

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

1442

# indicating unlimited maximum quota.

1443

#

1444

# Used by group-based quotas only.

Bu Sun Kim

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

[diff] [blame]

1445

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

1446

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

1447

# defined within the service config.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1448

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

1449

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

1450

# backend system.

1451

#

1452

# Here are some examples:

1453

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

1454

#

1455

# Note: the order of unit components is insignificant.

1456

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

Bu Sun Kim

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

[diff] [blame]

1457

},

1458

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1459

},

1460

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

1461

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1469

# - google.foo.v1.AnotherError

1470

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

1471

"A String",

1472

],

1473

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

1474

#

1475

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

1476

{ # A custom error rule.

1477

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

Bu Sun Kim

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

[diff] [blame]

1478

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1479

# Refer to selector for syntax details.

1480

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

1481

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

},

],

},

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

1486

#

1487

# Example for an API targeted for external use:

1488

#

1489

# name: calendar.googleapis.com

1490

# authentication:

1491

# providers:

1492

# - id: google_calendar_auth

1493

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

1494

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

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

1499

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

1500

#

1501

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

1502

{ # Authentication rules for the service.

1503

#

1504

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

1505

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

1506

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

1507

# request.

1508

#

1509

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

1510

# ignored.

1511

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

1512

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

1513

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

1514

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

1515

#

1516

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

1517

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

1518

#

1519

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

1520

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

1521

# the OAuth scope across all of those APIs.

1522

#

1523

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

1524

# management about how developers will use them in practice.

1525

#

1526

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

1527

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

1528

# due to the backend requiring additional scopes or permissions.

1529

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

1530

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

#

# Example:

#

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

1535

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

Bu Sun Kim

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

[diff] [blame]

1536

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1537

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

1538

{ # User-defined authentication requirements, including support for

1539

# [JSON Web Token

1540

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

1541

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

#

# Example:

#

# provider_id: bookstore_auth

1546

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

1547

# implemented and accepted in all the runtime components.

1548

#

1549

# The list of JWT

1550

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

1551

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

1552

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

1553

# "https://Service_name/API_name"

1554

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

1555

# LibraryService API will only accept JWTs with the following audience

1556

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1561

# bookstore_web.apps.googleusercontent.com

1562

},

1563

],

1564

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

Bu Sun Kim

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

[diff] [blame]

1565

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

1566

#

1567

# Refer to selector for syntax details.

Bu Sun Kim

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

[diff] [blame]

1568

},

1569

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1570

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

1571

{ # Configuration for an authentication provider, including support for

1572

# [JSON Web Token

1573

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

1574

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

1575

# `AuthRequirement.provider_id`.

1576

#

1577

# Example: "bookstore_auth".

1578

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

1579

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

1580

# Usually a URL or an email address.

1581

#

1582

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

1583

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

1584

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

1585

# [OpenID

1586

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

1587

# Optional if the key set document:

1588

# - can be retrieved from

1589

# [OpenID

1590

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

1591

# the issuer.

1592

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

1593

# service account).

1594

#

1595

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

1596

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

1597

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

1598

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

1599

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

1600

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

1601

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

1602

# will be accepted.

1603

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

1604

# accept JWTs with the following audiences:

1605

# -

1606

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

1607

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1612

# bookstore_web.apps.googleusercontent.com

1613

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

1614

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

1615

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

1616

#

1617

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

1618

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

1619

# all headers first, then URL query parameters.

1620

#

1621

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

1622

# 1) Authorization: Bearer

1623

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

1624

# 3) access_token query parameter

1625

#

1626

# Default locations can be specified as followings:

1627

# jwt_locations:

1628

# - header: Authorization

1629

# value_prefix: "Bearer "

1630

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

1631

# - query: access_token

1632

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

1633

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

1634

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

1635

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

1636

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

1637

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

1638

# extracted after the prefix is removed.

1639

#

1640

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

1641

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

1642

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

},

],

},

],

Bu Sun Kim

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

[diff] [blame]

1647

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

1648

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

1649

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

1650

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

1651

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

1652

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

1653

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

1654

# which cannot be resolved against the associated IDL files.

1655

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

1656

#

1657

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

1658

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

1659

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

1660

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

1661

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

1662

# this message itself. See https://cloud.google.com/apis/design/glossary for

1663

# detailed terminology.

1664

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

1665

# message.

1666

# protobuf element, like the file in which it is defined.

1667

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1668

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1669

},

1670

"syntax": "A String", # The source syntax of the service.

1671

"methods": [ # The methods of this interface, in unspecified order.

1672

{ # Method represents a method of an API interface.

1673

"options": [ # Any metadata attached to the method.

1674

{ # A protocol buffer option, which can be attached to a message, field,

1675

# enumeration, etc.

1676

"value": { # The option's value packed in an Any message. If the value is a primitive,

1677

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1678

# should be used. If the value is an enum, it should be stored as an int32

1679

# value using the google.protobuf.Int32Value type.

1680

"a_key": "", # Properties of the object. Contains field @type with type URL.

1681

},

1682

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1683

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1684

# For custom options, it should be the fully-qualified name. For example,

1685

# `"google.api.http"`.

1686

},

1687

],

1688

"responseStreaming": True or False, # If true, the response is streamed.

1689

"syntax": "A String", # The source syntax of this method.

1690

"requestTypeUrl": "A String", # A URL of the input message type.

1691

"name": "A String", # The simple name of this method.

1692

"responseTypeUrl": "A String", # The URL of the output message type.

1693

"requestStreaming": True or False, # If true, the request is streamed.

1694

},

1695

],

1696

"name": "A String", # The fully qualified name of this interface, including package name

1697

# followed by the interface's simple name.

1698

"version": "A String", # A version string for this interface. If specified, must have the form

1699

# `major-version.minor-version`, as in `1.10`. If the minor version is

1700

# omitted, it defaults to zero. If the entire version field is empty, the

1701

# major version is derived from the package name, as outlined below. If the

1702

# field is not empty, the version in the package name will be verified to be

1703

# consistent with what is provided here.

1704

#

1705

# The versioning schema uses [semantic

1706

# versioning](http://semver.org) where the major version number

1707

# indicates a breaking change and the minor version an additive,

1708

# non-breaking change. Both version numbers are signals to users

1709

# what to expect from different versions, and should be carefully

1710

# chosen based on the product plan.

1711

#

1712

# The major version is also reflected in the package name of the

1713

# interface, which must end in `v<major-version>`, as in

1714

# `google.feature.v1`. For major versions 0 and 1, the suffix can

1715

# be omitted. Zero major versions must only be used for

1716

# experimental, non-GA interfaces.

1717

"options": [ # Any metadata attached to the interface.

1718

{ # A protocol buffer option, which can be attached to a message, field,

1719

# enumeration, etc.

1720

"value": { # The option's value packed in an Any message. If the value is a primitive,

1721

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1722

# should be used. If the value is an enum, it should be stored as an int32

1723

# value using the google.protobuf.Int32Value type.

1724

"a_key": "", # Properties of the object. Contains field @type with type URL.

1725

},

1726

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1727

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1728

# For custom options, it should be the fully-qualified name. For example,

1729

# `"google.api.http"`.

1730

},

1731

],

1732

"mixins": [ # Included interfaces. See Mixin.

1733

{ # Declares an API Interface to be included in this interface. The including

1734

# interface must redeclare all the methods from the included interface, but

1735

# documentation and options are inherited as follows:

1736

#

1737

# - If after comment and whitespace stripping, the documentation

1738

# string of the redeclared method is empty, it will be inherited

1739

# from the original method.

1740

#

1741

# - Each annotation belonging to the service config (http,

1742

# visibility) which is not set in the redeclared method will be

1743

# inherited.

1744

#

1745

# - If an http annotation is inherited, the path pattern will be

1746

# modified as follows. Any version prefix will be replaced by the

1747

# version of the including interface plus the root path if

1748

# specified.

1749

#

1750

# Example of a simple mixin:

1751

#

1752

# package google.acl.v1;

1753

# service AccessControl {

1754

# // Get the underlying ACL object.

1755

# rpc GetAcl(GetAclRequest) returns (Acl) {

1756

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

1761

# service Storage {

1762

# // rpc GetAcl(GetAclRequest) returns (Acl);

1763

#

1764

# // Get a data record.

1765

# rpc GetData(GetDataRequest) returns (Data) {

1766

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

1771

#

1772

# apis:

1773

# - name: google.storage.v2.Storage

1774

# mixins:

1775

# - name: google.acl.v1.AccessControl

1776

#

1777

# The mixin construct implies that all methods in `AccessControl` are

1778

# also declared with same name and request/response types in

1779

# `Storage`. A documentation generator or annotation processor will

1780

# see the effective `Storage.GetAcl` method after inherting

1781

# documentation and annotations as follows:

1782

#

1783

# service Storage {

1784

# // Get the underlying ACL object.

1785

# rpc GetAcl(GetAclRequest) returns (Acl) {

1786

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

1792

#

1793

# If the `root` field in the mixin is specified, it should be a

1794

# relative path under which inherited HTTP paths are placed. Example:

1795

#

1796

# apis:

1797

# - name: google.storage.v2.Storage

1798

# mixins:

1799

# - name: google.acl.v1.AccessControl

1800

# root: acls

1801

#

1802

# This implies the following inherited HTTP annotation:

1803

#

1804

# service Storage {

1805

# // Get the underlying ACL object.

1806

# rpc GetAcl(GetAclRequest) returns (Acl) {

1807

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

1812

# are rooted.

1813

"name": "A String", # The fully qualified name of the interface which is included.

},

],

},

],

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

1819

# by the client for tracking purpose. Must be no longer than 63 characters

1820

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

1821

# empty, the server may choose to generate one instead.

1822

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

1823

# with the same name as the service is automatically generated to service all

1824

# defined APIs.

1825

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

1826

# A service may expose any number of endpoints, and all endpoints share the

1827

# same service configuration, such as quota configuration and monitoring

1828

# configuration.

1829

#

1830

# Example service configuration:

1831

#

1832

# name: library-example.googleapis.com

1833

# endpoints:

1834

# # Below entry makes 'google.example.library.v1.Library'

1835

# # API be served from endpoint address library-example.googleapis.com.

1836

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

1837

# # it to decide whether the subsequent cross-origin request is

1838

# # allowed to proceed.

1839

# - name: library-example.googleapis.com

1840

# allow_cors: true

1841

"name": "A String", # The canonical name of this endpoint.

1842

"allowCors": True or False, # Allowing

1843

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

1844

# cross-domain traffic, would allow the backends served from this endpoint to

1845

# receive and respond to HTTP OPTIONS requests. The response will be used by

1846

# the browser to determine whether the subsequent cross-origin request is

1847

# allowed to proceed.

1848

"target": "A String", # The specification of an Internet routable address of API frontend that will

1849

# handle requests to this [API

1850

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

1851

# either a valid IPv4 address or a fully-qualified domain name. For example,

1852

# "8.8.8.8" or "myservice.appspot.com".

1853

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

1854

# please specify multiple google.api.Endpoint for each of the intended

1855

# aliases.

1856

#

1857

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"systemParameters": { # ### System parameter configuration # System parameter configuration.

1863

#

1864

# A system parameter is a special kind of parameter defined by the API

1865

# system, not by an individual API. It is typically mapped to an HTTP header

1866

# and/or a URL query parameter. This configuration specifies which methods

1867

# change the names of the system parameters.

1868

"rules": [ # Define system parameters.

1869

#

1870

# The parameters defined here will override the default parameters

1871

# implemented by the system. If this field is missing from the service

1872

# config, default system parameters will be used. Default system parameters

1873

# and names is implementation-dependent.

1874

#

1875

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1883

#

1884

#

1885

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1890

# parameters:

1891

# - name: api_key

1892

# http_header: Api-Key1

1893

# - name: api_key

1894

# http_header: Api-Key2

1895

#

1896

# **NOTE:** All service configuration rules follow "last one wins" order.

1897

{ # Define a system parameter rule mapping system parameter definitions to

1898

# methods.

1899

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

1900

# For a given method call, only one of them should be used. If multiple

1901

# names are used the behavior is implementation-dependent.

1902

# If none of the specified names are present the behavior is

1903

# parameter-dependent.

1904

{ # Define a parameter's name and location. The parameter may be passed as either

1905

# an HTTP header or a URL query parameter, and if both are passed the behavior

1906

# is implementation-dependent.

1907

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

1908

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

1909

# insensitive.

1910

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

# sensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1915

# methods in all APIs.

1916

#

1917

# Refer to selector for syntax details.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

1922

# by the Service.monitoring and Service.logging configurations.

1923

{ # An object that describes the schema of a MonitoredResource object using a

1924

# type name and a set of labels. For example, the monitored resource

1925

# descriptor for Google Compute Engine VM instances has a type of

1926

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

1927

# `"zone"` to identify particular VM instances.

1928

#

1929

# Different services can support different monitored resource types.

1930

#

1931

# The following are specific rules to service defined monitored resources for

1932

# Monitoring and Logging:

1933

#

1934

# * The `type`, `display_name`, `description`, `labels` and `launch_stage`

1935

# fields are all required.

1936

# * The first label of the monitored resource descriptor must be

1937

# `resource_container`. There are legacy monitored resource descritptors

1938

# start with `project_id`.

1939

# * It must include a `location` label.

1940

# * Maximum of default 5 service defined monitored resource descriptors

1941

# is allowed per service.

1942

# * Maximum of default 10 labels per monitored resource is allowed.

1943

#

1944

# The default maximum limit can be overridden. Please follow

1945

# https://cloud.google.com/monitoring/quotas

1946

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

1947

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

1948

# {type} is the value of the `type` field in this object and

1949

# {project_id} is a project ID that provides API-specific context for

1950

# accessing the type. APIs that do not use project information can use the

1951

# resource name format `"monitoredResourceDescriptors/{type}"`.

1952

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

1953

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

1954

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

1955

# without any article or other determiners. For example,

1956

# `"Google Cloud SQL Database"`.

1957

"labels": [ # Required. A set of labels used to describe instances of this monitored

1958

# resource type.

1959

# The label key name must follow:

1960

#

1961

# * Only upper and lower-case letters, digits and underscores (_) are

1962

# allowed.

1963

# * Label name must start with a letter or digit.

1964

# * The maximum length of a label name is 100 characters.

1965

#

1966

# For example, an individual Google Cloud SQL database is

1967

# identified by values for the labels `database_id` and `location`.

1968

{ # A description of a label.

1969

"valueType": "A String", # The type of data that can be assigned to the label.

1970

"description": "A String", # A human-readable description for the label.

1971

"key": "A String", # The label key.

1972

},

1973

],

1974

"description": "A String", # Optional. A detailed description of the monitored resource type that might

1975

# be used in documentation.

1976

"type": "A String", # Required. The monitored resource type. For example, the type

1977

# `cloudsql_database` represents databases in Google Cloud SQL.

1978

#

1979

# All service defined monitored resource types must be prefixed with the

1980

# service name, in the format of `{service name}/{relative resource name}`.

1981

# The relative resource name must follow:

1982

#

1983

# * Only upper and lower-case letters and digits are allowed.

1984

# * It must start with upper case character and is recommended to use Upper

1985

# Camel Case style.

1986

# * The maximum number of characters allowed for the relative_resource_name

1987

# is 100.

1988

#

1989

# Note there are legacy service monitored resources not following this rule.

1990

},

1991

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1992

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1993

#

1994

# Example:

1995

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

2001

# - google.rpc.context.OriginContext

2002

#

2003

# The above specifies that all methods in the API request

2004

# `google.rpc.context.ProjectContext` and

2005

# `google.rpc.context.OriginContext`.

2006

#

2007

# Available context types are defined in package

2008

# `google.rpc.context`.

2009

#

2010

# This also provides mechanism to whitelist any protobuf message extension that

2011

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

2012

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

2013

# 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"

2021

# allowed_request_extensions:

2022

# - google.foo.v1.NewExtension

2023

# allowed_response_extensions:

2024

# - google.foo.v1.NewExtension

2025

#

2026

# You can also specify extension ID instead of fully qualified extension name

2027

# here.

2028

"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]

2029

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2030

# **NOTE:** All service configuration rules follow "last one wins" order.

2031

{ # A context rule provides information about the context for an individual API

2032

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2033

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2034

#

2035

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2036

"requested": [ # A list of full type names of requested contexts.

2037

"A String",

2038

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2039

"provided": [ # A list of full type names of provided contexts.

2040

"A String",

2041

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2042

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

2043

# side channel from client to backend.

2044

"A String",

2045

],

2046

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

2047

# side channel from backend to client.

2048

"A String",

2049

],

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:

2062

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2063

{ # `Service` is the root object of Google service configuration schema. It

2064

# describes basic information about a service, such as the name and the

2065

# title, and delegates other aspects to sub-sections. Each sub-section is

2066

# either a proto message or a repeated proto message that configures a

2067

# 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]

2072

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2073

# name: calendar.googleapis.com

2074

# title: Google Calendar API

2075

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2076

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2077

# authentication:

2078

# providers:

2079

# - id: google_calendar_auth

2080

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2081

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2082

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2083

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2084

# requirements:

2085

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2086

"enums": [ # A list of all enum types included in this API service. Enums

2087

# referenced directly or indirectly by the `apis` are automatically

2088

# included. Enums which are not referenced but shall be included

2089

# should be listed here by name. Example:

2090

#

2091

# enums:

2092

# - name: google.someapi.v1.SomeEnum

2093

{ # Enum type definition.

2094

"options": [ # Protocol buffer options.

2095

{ # A protocol buffer option, which can be attached to a message, field,

2096

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2097

"value": { # The option's value packed in an Any message. If the value is a primitive,

2098

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2099

# should be used. If the value is an enum, it should be stored as an int32

2100

# value using the google.protobuf.Int32Value type.

2101

"a_key": "", # Properties of the object. Contains field @type with type URL.

2102

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2103

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2104

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2105

# For custom options, it should be the fully-qualified name. For example,

2106

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2107

},

2108

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2109

"enumvalue": [ # Enum value definitions.

2110

{ # Enum value definition.

2111

"name": "A String", # Enum value name.

2112

"options": [ # Protocol buffer options.

2113

{ # A protocol buffer option, which can be attached to a message, field,

2114

# enumeration, etc.

2115

"value": { # The option's value packed in an Any message. If the value is a primitive,

2116

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2117

# should be used. If the value is an enum, it should be stored as an int32

2118

# value using the google.protobuf.Int32Value type.

2119

"a_key": "", # Properties of the object. Contains field @type with type URL.

2120

},

2121

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2122

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2123

# For custom options, it should be the fully-qualified name. For example,

2124

# `"google.api.http"`.

2125

},

2126

],

2127

"number": 42, # Enum value number.

2128

},

2129

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2130

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2131

# protobuf element, like the file in which it is defined.

2132

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2133

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2134

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2135

"name": "A String", # Enum type name.

2136

"syntax": "A String", # The source syntax.

2137

},

2138

],

2139

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

2140

"rules": [ # A list of API backend rules that apply to individual API methods.

2141

#

2142

# **NOTE:** All service configuration rules follow "last one wins" order.

2143

{ # A backend rule provides configuration for an individual API element.

2144

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

2145

# original "Authorization" HTTP header will be preserved. If the header is

2146

# used to carry the original token and is expected by the backend, this

2147

# field must be set to true to preserve the header.

2148

"address": "A String", # The address of the API backend.

2149

#

2150

# The scheme is used to determine the backend protocol and security.

2151

# The following schemes are accepted:

2152

#

2153

# 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

2160

# may cause constrasting behaviors across platforms.

2161

#

2162

# If the port is unspecified, the default is:

2163

# - 80 for schemes without TLS

2164

# - 443 for schemes with TLS

2165

#

2166

# For HTTP backends, use protocol

2167

# to specify the protocol version.

2168

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

2169

# value lower than this will be rejected.

2170

"selector": "A String", # Selects the methods to which this rule applies.

2171

#

2172

# Refer to selector for syntax details.

2173

"protocol": "A String", # The protocol used for sending a request to the backend.

2174

# The supported values are "http/1.1" and "h2".

2175

#

2176

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

2186

# to "h2" for improved performance.

2187

#

2188

# Configuring this field to non-default values is only supported for secure

2189

# HTTP backends. This field will be ignored for all other backends.

2190

#

2191

# See

2192

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

2193

# for more details on the supported values.

2194

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

2195

# operation. The default is no deadline.

2196

"pathTranslation": "A String",

2197

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

2198

# This ID token will be added in the HTTP "authorization" header, and sent

2199

# to the backend.

2200

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

2201

# varies based on the request protocol and deployment environment.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

2206

# It serves similar purpose as [google.api.Service.types], except that

2207

# these types are not needed by user-defined APIs. Therefore, they will not

2208

# show up in the generated discovery doc. This field should only be used

2209

# to define system APIs in ESF.

2210

{ # A protocol buffer message type.

2211

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2212

# protobuf element, like the file in which it is defined.

2213

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2214

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2215

},

2216

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2217

"A String",

2218

],

2219

"fields": [ # The list of fields.

2220

{ # A single field of a message type.

2221

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2222

# types. The first type has index 1; zero means the type is not in the list.

2223

"name": "A String", # The field name.

2224

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2225

"packed": True or False, # Whether to use alternative packed wire representation.

2226

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2227

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2228

"cardinality": "A String", # The field cardinality.

2229

"jsonName": "A String", # The field JSON name.

2230

"kind": "A String", # The field type.

2231

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2232

{ # A protocol buffer option, which can be attached to a message, field,

2233

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2234

"value": { # The option's value packed in an Any message. If the value is a primitive,

2235

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2236

# should be used. If the value is an enum, it should be stored as an int32

2237

# value using the google.protobuf.Int32Value type.

2238

"a_key": "", # Properties of the object. Contains field @type with type URL.

2239

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2240

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2241

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2242

# For custom options, it should be the fully-qualified name. For example,

2243

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2244

},

2245

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2246

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2247

},

2248

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2249

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2250

{ # A protocol buffer option, which can be attached to a message, field,

2251

# enumeration, etc.

2252

"value": { # The option's value packed in an Any message. If the value is a primitive,

2253

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2254

# should be used. If the value is an enum, it should be stored as an int32

2255

# value using the google.protobuf.Int32Value type.

2256

"a_key": "", # Properties of the object. Contains field @type with type URL.

2257

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2258

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2259

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2260

# For custom options, it should be the fully-qualified name. For example,

2261

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2262

},

2263

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2264

"syntax": "A String", # The source syntax.

2265

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2266

},

2267

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2268

"name": "A String", # The service name, which is a DNS-like logical identifier for the

2269

# service, such as `calendar.googleapis.com`. The service name

2270

# typically goes through DNS verification to make sure the owner

2271

# of the service also owns the DNS name.

2272

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

2273

"sourceFiles": [ # All files used during config generation.

2274

{

2275

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2276

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2277

],

2278

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2279

"billing": { # Billing related configuration of the service. # Billing configuration.

2280

#

2281

# The following example shows how to configure monitored resources and metrics

2282

# for billing, `consumer_destinations` is the only supported destination and

2283

# the monitored resources need at least one label key

2284

# `cloud.googleapis.com/location` to indicate the location of the billing

2285

# usage, using different monitored resources between monitoring and billing is

2286

# recommended so they can be evolved independently:

2287

#

2288

#

2289

# monitored_resources:

2290

# - type: library.googleapis.com/billing_branch

2291

# labels:

2292

# - key: cloud.googleapis.com/location

2293

# description: |

2294

# Predefined label to support billing location restriction.

2295

# - key: city

2296

# description: |

2297

# Custom label to define the city where the library branch is located

2298

# in.

2299

# - key: name

2300

# description: Custom label to define the name of the library branch.

2301

# metrics:

2302

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

2308

# - monitored_resource: library.googleapis.com/billing_branch

2309

# metrics:

2310

# - library.googleapis.com/book/borrowed_count

2311

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

2312

# There can be multiple consumer destinations per service, each one must have

2313

# a different monitored resource type. A metric can be used in at most

2314

# one consumer destination.

2315

{ # Configuration of a specific billing destination (Currently only support

2316

# bill against consumer project).

2317

"metrics": [ # Names of the metrics to report to this billing destination.

2318

# Each name must be defined in Service.metrics section.

2319

"A String",

2320

],

2321

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2322

# Service.monitored_resources section.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

2327

#

2328

# The example below shows how to configure monitored resources and metrics

2329

# for monitoring. In the example, a monitored resource and two metrics are

2330

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2331

# to both producer and consumer projects, whereas the

2332

# `library.googleapis.com/book/num_overdue` metric is only sent to the

2333

# consumer project.

2334

#

2335

# monitored_resources:

2336

# - type: library.googleapis.com/Branch

2337

# display_name: "Library Branch"

2338

# description: "A branch of a library."

2339

# launch_stage: GA

2340

# labels:

2341

# - key: resource_container

2342

# description: "The Cloud container (ie. project id) for the Branch."

2343

# - key: location

2344

# description: "The location of the library branch."

2345

# - key: branch_id

2346

# description: "The id of the branch."

2347

# metrics:

2348

# - name: library.googleapis.com/book/returned_count

2349

# display_name: "Books Returned"

2350

# description: "The count of books that have been returned."

# launch_stage: GA

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

2358

# - name: library.googleapis.com/book/num_overdue

2359

# display_name: "Books Overdue"

2360

# description: "The current number of overdue books."

# launch_stage: GA

# metric_kind: GAUGE

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

2368

# monitoring:

2369

# producer_destinations:

2370

# - monitored_resource: library.googleapis.com/Branch

2371

# metrics:

2372

# - library.googleapis.com/book/returned_count

2373

# consumer_destinations:

2374

# - monitored_resource: library.googleapis.com/Branch

2375

# metrics:

2376

# - library.googleapis.com/book/returned_count

2377

# - library.googleapis.com/book/num_overdue

2378

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

2379

# There can be multiple producer destinations. A monitored resource type may

2380

# appear in multiple monitoring destinations if different aggregations are

2381

# needed for different sets of metrics associated with that monitored

2382

# resource type. A monitored resource and metric pair may only be used once

2383

# in the Monitoring configuration.

2384

{ # Configuration of a specific monitoring destination (the producer project

2385

# or the consumer project).

2386

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2387

# Service.monitored_resources section.

2388

"metrics": [ # Types of the metrics to report to this monitoring destination.

2389

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

2395

# There can be multiple consumer destinations. A monitored resource type may

2396

# appear in multiple monitoring destinations if different aggregations are

2397

# needed for different sets of metrics associated with that monitored

2398

# resource type. A monitored resource and metric pair may only be used once

2399

# in the Monitoring configuration.

2400

{ # Configuration of a specific monitoring destination (the producer project

2401

# or the consumer project).

2402

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2403

# Service.monitored_resources section.

2404

"metrics": [ # Types of the metrics to report to this monitoring destination.

2405

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"logging": { # Logging configuration of the service. # Logging configuration.

2412

#

2413

# The following example shows how to configure logs to be sent to the

2414

# producer and consumer projects. In the example, the `activity_history`

2415

# log is sent to both the producer and consumer projects, whereas the

2416

# `purchase_history` log is only sent to the producer project.

2417

#

2418

# monitored_resources:

2419

# - type: library.googleapis.com/branch

2420

# labels:

2421

# - key: /city

2422

# description: The city where the library branch is located in.

2423

# - key: /name

2424

# description: The name of the branch.

2425

# logs:

2426

# - name: activity_history

2427

# labels:

2428

# - key: /customer_id

2429

# - name: purchase_history

2430

# logging:

2431

# producer_destinations:

2432

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

2437

# - monitored_resource: library.googleapis.com/branch

2438

# logs:

2439

# - activity_history

2440

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2441

# There can be multiple producer destinations, each one must have a

2442

# different monitored resource type. A log can be used in at most

2443

# one producer destination.

2444

{ # Configuration of a specific logging destination (the producer project

2445

# or the consumer project).

2446

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

2447

# Service.monitored_resources section.

2448

"logs": [ # Names of the logs to be sent to this destination. Each name must

2449

# be defined in the Service.logs section. If the log name is

2450

# not a domain scoped name, it will be automatically prefixed with

2451

# the service name followed by "/".

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

2457

# There can be multiple consumer destinations, each one must have a

2458

# different monitored resource type. A log can be used in at most

2459

# one consumer destination.

2460

{ # Configuration of a specific logging destination (the producer project

2461

# or the consumer project).

2462

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

2463

# Service.monitored_resources section.

2464

"logs": [ # Names of the logs to be sent to this destination. Each name must

2465

# be defined in the Service.logs section. If the log name is

2466

# not a domain scoped name, it will be automatically prefixed with

2467

# the service name followed by "/".

"A String",

],

},

],

},

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2474

# service controller handles features like abuse, quota, billing, logging,

2475

# monitoring, etc.

2476

"environment": "A String", # The service control environment to use. If empty, no control plane

2477

# feature (like quota and billing) will be enabled.

2478

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2479

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

2480

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

2481

# service. Each requirement is of the form <service.name>/<requirement-id>;

2482

# for example 'serviceusage.googleapis.com/billing-enabled'.

2483

"A String",

2484

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2485

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

2486

#

2487

#

2488

# Use this field to configure per-product per-project service identity.

2489

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

2494

# display_name: "Cloud XXX Service Agent"

2495

# description: "Used as the identity of Cloud XXX to access resources"

2496

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

2497

#

2498

# An example name would be:

2499

# `projects/123456789`

2500

"description": "A String", # Optional. A user-specified opaque description of the service account.

2501

# Must be less than or equal to 256 UTF-8 bytes.

2502

"displayName": "A String", # Optional. A user-specified name for the service account.

2503

# Must be less than or equal to 100 UTF-8 bytes.

2504

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2505

"rules": [ # A list of usage rules that apply to individual API methods.

2506

#

2507

# **NOTE:** All service configuration rules follow "last one wins" order.

2508

{ # Usage configuration rules for the service.

2509

#

2510

# NOTE: Under development.

2511

#

2512

#

2513

# Use this rule to configure unregistered calls for the service. Unregistered

2514

# calls are calls that do not contain consumer project identity.

2515

# (Example: calls that do not contain an API key).

2516

# By default, API methods do not allow unregistered calls, and each method call

2517

# must be identified by a consumer project identity. Use this rule to

2518

# allow/disallow unregistered calls.

2519

#

2520

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

2526

#

2527

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

2532

# allow_unregistered_calls: true

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2533

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

2534

# plane features, such as quota and billing, will not be available.

2535

# This flag is used by Google Cloud Endpoints to bypass checks for internal

2536

# methods, such as service health check methods.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2537

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2538

# methods in all APIs.

2539

#

2540

# Refer to selector for syntax details.

2541

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

2542

# that don't identify any user or application.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2543

},

2544

],

2545

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

2546

# service producer.

2547

#

2548

# Google Service Management currently only supports

2549

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2550

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2551

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2552

# documented in https://cloud.google.com/pubsub/docs/overview.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2553

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2554

"types": [ # A list of all proto message types included in this API service.

2555

# Types referenced directly or indirectly by the `apis` are

2556

# automatically included. Messages which are not referenced but

2557

# shall be included, such as types used by the `google.protobuf.Any` type,

2558

# should be listed here by name. Example:

2559

#

2560

# types:

2561

# - name: google.protobuf.Int32

2562

{ # A protocol buffer message type.

2563

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2564

# protobuf element, like the file in which it is defined.

2565

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2566

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2567

},

2568

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2569

"A String",

2570

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2571

"fields": [ # The list of fields.

2572

{ # A single field of a message type.

2573

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2574

# types. The first type has index 1; zero means the type is not in the list.

2575

"name": "A String", # The field name.

2576

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2577

"packed": True or False, # Whether to use alternative packed wire representation.

2578

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2579

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2580

"cardinality": "A String", # The field cardinality.

2581

"jsonName": "A String", # The field JSON name.

2582

"kind": "A String", # The field type.

2583

"options": [ # The protocol buffer options.

2584

{ # A protocol buffer option, which can be attached to a message, field,

2585

# enumeration, etc.

2586

"value": { # The option's value packed in an Any message. If the value is a primitive,

2587

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2588

# should be used. If the value is an enum, it should be stored as an int32

2589

# value using the google.protobuf.Int32Value type.

2590

"a_key": "", # Properties of the object. Contains field @type with type URL.

2591

},

2592

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2593

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2594

# For custom options, it should be the fully-qualified name. For example,

2595

# `"google.api.http"`.

2596

},

2597

],

2598

"number": 42, # The field number.

2599

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2600

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2601

"options": [ # The protocol buffer options.

2602

{ # A protocol buffer option, which can be attached to a message, field,

2603

# enumeration, etc.

2604

"value": { # The option's value packed in an Any message. If the value is a primitive,

2605

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2606

# should be used. If the value is an enum, it should be stored as an int32

2607

# value using the google.protobuf.Int32Value type.

2608

"a_key": "", # Properties of the object. Contains field @type with type URL.

2609

},

2610

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2611

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2612

# For custom options, it should be the fully-qualified name. For example,

2613

# `"google.api.http"`.

2614

},

2615

],

2616

"syntax": "A String", # The source syntax.

2617

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2618

},

2619

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2620

"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]

2621

# HttpRule, each specifying the mapping of an RPC method

2622

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2623

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

2624

# cases of single segment matches in reserved expansion, where "%2F" will be

2625

# left encoded.

2626

#

2627

# The default behavior is to not decode RFC 6570 reserved characters in multi

2628

# segment matches.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2629

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2630

#

2631

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2632

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2633

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2634

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

2635

# more HTTP REST endpoints. It allows developers to build a single API service

2636

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

2637

# APIs](https://github.com/googleapis/googleapis),

2638

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

2639

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

2640

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

2641

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2642

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2643

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

2644

# how different portions of the gRPC request message are mapped to the URL

2645

# path, URL query parameters, and HTTP request body. It also controls how the

2646

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

2647

# typically specified as an `google.api.http` annotation on the gRPC method.

2648

#

2649

# Each mapping specifies a URL path template and an HTTP method. The path

2650

# template may refer to one or more fields in the gRPC request message, as long

2651

# as each field is a non-repeated field with a primitive (non-message) type.

2652

# The path template controls how fields of the request message are mapped to

2653

# the URL path.

2654

#

2655

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2656

#

2657

# service Messaging {

2658

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2659

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2660

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2661

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2662

# }

2663

# }

2664

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2665

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2666

# }

2667

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2668

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2669

# }

2670

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2671

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2672

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2673

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2674

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2675

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2676

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2677

# Any fields in the request message which are not bound by the path template

2678

# automatically become HTTP query parameters if there is no HTTP request body.

2679

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2680

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2681

# service Messaging {

2682

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2683

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2684

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2685

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2686

# }

2687

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2688

# message GetMessageRequest {

2689

# message SubMessage {

2690

# string subfield = 1;

2691

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2692

# string message_id = 1; // Mapped to URL path.

2693

# int64 revision = 2; // Mapped to URL query parameter `revision`.

2694

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2695

# }

2696

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2697

# This enables a HTTP JSON to RPC mapping as below:

2698

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2699

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2700

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2701

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2702

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

2703

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2704

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2705

# Note that fields which are mapped to URL query parameters must have a

2706

# primitive type or a repeated primitive type or a non-repeated message type.

2707

# 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]

2708

# 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]

2709

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

2710

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2711

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2712

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2713

# specifies the mapping. Consider a REST update method on the

2714

# message resource collection:

2715

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2716

# service Messaging {

2717

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2718

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2719

# patch: "/v1/messages/{message_id}"

2720

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

2725

# string message_id = 1; // mapped to the URL

2726

# Message message = 2; // mapped to the body

2727

# }

2728

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2729

# The following HTTP JSON to RPC mapping is enabled, where the

2730

# representation of the JSON in the request body is determined by

2731

# protos JSON encoding:

2732

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2733

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2734

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2735

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2736

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2737

#

2738

# The special name `*` can be used in the body mapping to define that

2739

# every field not bound by the path template should be mapped to the

2740

# request body. This enables the following alternative definition of

2741

# the update method:

2742

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2743

# service Messaging {

2744

# rpc UpdateMessage(Message) returns (Message) {

2745

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2746

# patch: "/v1/messages/{message_id}"

2747

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

2753

# string text = 2;

2754

# }

2755

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2756

#

2757

# The following HTTP JSON to RPC mapping is enabled:

2758

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2759

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2760

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2761

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2762

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2763

#

2764

# Note that when using `*` in the body mapping, it is not possible to

2765

# 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]

2766

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2767

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2768

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2769

#

2770

# It is possible to define multiple HTTP methods for one RPC by using

2771

# the `additional_bindings` option. Example:

2772

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2773

# service Messaging {

2774

# rpc GetMessage(GetMessageRequest) returns (Message) {

2775

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2776

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2777

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2778

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2779

# }

2780

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2781

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2782

# }

2783

# message GetMessageRequest {

2784

# string message_id = 1;

2785

# string user_id = 2;

2786

# }

2787

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2788

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2789

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2790

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2791

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2792

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

2793

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

2794

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2795

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2796

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2797

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2798

# 1. Leaf request fields (recursive expansion nested messages in the request

2799

# message) are classified into three categories:

2800

# - Fields referred by the path template. They are passed via the URL path.

2801

# - Fields referred by the HttpRule.body. They are passed via the HTTP

2802

# request body.

2803

# - All other fields are passed via the URL query parameters, and the

2804

# parameter name is the field path in the request message. A repeated

2805

# field can be represented as multiple query parameters under the same

2806

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2807

# 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]

2808

# are passed via URL path and HTTP request body.

2809

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

2810

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2811

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2812

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2813

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2814

# Template = "/" Segments [ Verb ] ;

2815

# Segments = Segment { "/" Segment } ;

2816

# Segment = "*" | "**" | LITERAL | Variable ;

2817

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2818

# FieldPath = IDENT { "." IDENT } ;

2819

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2820

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2821

# The syntax `*` matches a single URL path segment. The syntax `**` matches

2822

# zero or more URL path segments, which must be the last part of the URL path

2823

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2824

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2825

# The syntax `Variable` matches part of the URL path as specified by its

2826

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2827

# matches a single path segment, its template may be omitted, e.g. `{var}`

2828

# is equivalent to `{var=*}`.

2829

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2830

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

2831

# contains any reserved character, such characters should be percent-encoded

2832

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2833

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2834

# If a variable contains exactly one path segment, such as `"{var}"` or

2835

# `"{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]

2836

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

2837

# server side does the reverse decoding. Such variables show up in the

2838

# [Discovery

2839

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2840

# `{var}`.

2841

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2842

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

2843

# 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]

2844

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2845

# 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]

2846

# unchanged. Such variables show up in the

2847

# [Discovery

2848

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2849

# `{+var}`.

2850

#

2851

# ## Using gRPC API Service Configuration

2852

#

2853

# gRPC API Service Configuration (service config) is a configuration language

2854

# for configuring a gRPC service to become a user-facing product. The

2855

# service config is simply the YAML representation of the `google.api.Service`

2856

# proto message.

2857

#

2858

# As an alternative to annotating your proto file, you can configure gRPC

2859

# transcoding in your service config YAML files. You do this by specifying a

2860

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

2861

# effect as the proto annotation. This can be particularly useful if you

2862

# have a proto that is reused in multiple services. Note that any transcoding

2863

# specified in the service config will override any matching transcoding

2864

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

2871

# - selector: example.v1.Messaging.GetMessage

2872

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

2877

# proto to JSON conversion must follow the [proto3

2878

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

2879

#

2880

# While the single segment variable follows the semantics of

2881

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2882

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

2883

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

2884

# does not expand special characters like `?` and `#`, which would lead

2885

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

2886

# for multi segment variables.

2887

#

2888

# The path variables **must not** refer to any repeated or mapped field,

2889

# because client libraries are not capable of handling such variable expansion.

2890

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

2891

# The path variables **must not** capture the leading "/" character. The reason

2892

# 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]

2893

# character. For consistency, all path variables must share the same behavior.

2894

#

2895

# Repeated message fields must not be mapped to URL query parameters, because

2896

# no client library can support such complicated mapping.

2897

#

2898

# If an API needs to use a JSON array for request or response body, it can map

2899

# the request or response body to a repeated field. However, some gRPC

2900

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2901

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2902

"selector": "A String", # Selects a method to which this rule applies.

2903

#

2904

# Refer to selector for syntax details.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2905

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

2906

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

2907

# response body. When omitted, the entire response message will be used

2908

# as the HTTP response body.

2909

#

2910

# NOTE: The referred field must be present at the top-level of the response

2911

# message type.

2912

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

2913

# body, or `*` for mapping all request fields not captured by the path

2914

# pattern to the HTTP body, or omitted for not having any HTTP request body.

2915

#

2916

# NOTE: the referred field must be present at the top-level of the request

2917

# message type.

2918

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

2919

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2920

# not contain an `additional_bindings` field themselves (that is,

2921

# the nesting may only be one level deep).

2922

# Object with schema name: HttpRule

2923

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2924

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

2925

# included in the `pattern` field, such as HEAD, or "*" to leave the

2926

# HTTP method unspecified for this rule. The wild-card rule is useful

2927

# for services that provide content to Web (HTML) clients.

2928

"path": "A String", # The path matched by this custom verb.

2929

"kind": "A String", # The name of this custom HTTP verb.

2930

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2931

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

2932

# half-duplex streaming method.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2933

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2934

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

2935

# resources.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2936

},

2937

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2938

},

2939

"logs": [ # Defines the logs used by this service.

2940

{ # A description of a log type. Example in YAML format:

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2941

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2942

# - name: library.googleapis.com/activity_history

2943

# description: The history of borrowing and returning library items.

2944

# display_name: Activity

2945

# labels:

2946

# - key: /customer_id

2947

# description: Identifier of a library customer

2948

"description": "A String", # A human-readable description of this log. This information appears in

2949

# the documentation and can contain details.

2950

"labels": [ # The set of labels that are available to describe a specific log entry.

2951

# Runtime requests that contain labels not specified here are

2952

# considered invalid.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2953

{ # A description of a label.

2954

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2955

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2956

"key": "A String", # The label key.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2957

},

2958

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2959

"displayName": "A String", # The human-readable name for this log. This information appears on

2960

# the user interface and should be concise.

2961

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2962

# include the following characters: upper- and lower-case alphanumeric

2963

# characters [A-Za-z0-9], and punctuation characters including

2964

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

2965

},

2966

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

2967

"metrics": [ # Defines the metrics used by this service.

2968

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2969

# deleting or altering it stops data collection and makes the metric type's

2970

# existing data unusable.

2971

#

2972

# The following are specific rules for service defined Monitoring metric

2973

# descriptors:

2974

#

2975

# * `type`, `metric_kind`, `value_type`, `description`, and `display_name`

2976

# fields are all required. The `unit` field must be specified

2977

# if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.

2978

# * Maximum of default 500 metric descriptors per service is allowed.

2979

# * Maximum of default 10 labels per metric descriptor is allowed.

2980

#

2981

# The default maximum limit can be overridden. Please follow

2982

# https://cloud.google.com/monitoring/quotas

2983

"unit": "A String", # The units in which the metric value is reported. It is only applicable

2984

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

2985

# defines the representation of the stored metric values.

2986

#

2987

# Different systems may scale the values to be more easily displayed (so a

2988

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

2989

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

2990

# `KBy`, then the value of the metric is always in thousands of bytes, no

2991

# matter how it may be displayed..

2992

#

2993

# If you want a custom metric to record the exact number of CPU-seconds used

2994

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

2995

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

2996

# CPU-seconds, then the value is written as `12005`.

2997

#

2998

# Alternatively, if you want a custom metric to record data in a more

2999

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

3000

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

3001

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

3002

#

3003

# The supported units are a subset of [The Unified Code for Units of

3004

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3005

#

3006

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

# * `1` dimensionless

3015

#

3016

# **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)

3025

# * `Y` yotta (10^24)

3026

#

3027

# * `m` milli (10^-3)

3028

# * `u` micro (10^-6)

3029

# * `n` nano (10^-9)

3030

# * `p` pico (10^-12)

3031

# * `f` femto (10^-15)

3032

# * `a` atto (10^-18)

3033

# * `z` zepto (10^-21)

3034

# * `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:

3045

#

3046

# * `/` division or ratio (as an infix operator). For examples,

3047

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

3048

# have `/s` in a metric `unit`; rates should always be computed at

3049

# query time from the underlying cumulative or delta value).

3050

# * `.` multiplication or composition (as an infix operator). For

3051

# examples, `GBy.d` or `k{watt}.h`.

3052

#

3053

# The grammar for a unit is as follows:

3054

#

3055

# Expression = Component { "." Component } { "/" Component } ;

3056

#

3057

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

3067

# is used alone, then the unit is equivalent to `1`. For examples,

3068

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

3069

# * `NAME` is a sequence of non-blank printable ASCII characters not

3070

# containing `{` or `}`.

3071

# * `1` represents a unitary [dimensionless

3072

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

3073

# as in `1/s`. It is typically used when none of the basic units are

3074

# appropriate. For example, "new users per day" can be represented as

3075

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

3076

# users). Alternatively, "thousands of page views per day" would be

3077

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

3078

# value of `5.3` would mean "5300 page views per day").

3079

# * `%` represents dimensionless value of 1/100, and annotates values giving

3080

# a percentage (so the metric values are typically in the range of 0..100,

3081

# and a metric value `3` means "3 percent").

3082

# * `10^2.%` indicates a metric contains a ratio, typically in the range

3083

# 0..1, that will be multiplied by 100 and displayed as a percentage

3084

# (so a metric value `0.03` means "3 percent").

3085

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3086

# Use sentence case without an ending period, for example "Request count".

3087

# This field is optional but it is recommended to be set for any metrics

3088

# associated with user-visible concepts, such as Quota.

3089

"monitoredResourceTypes": [ # Read-only. If present, then a time

3090

# series, which is identified partially by

3091

# a metric type and a MonitoredResourceDescriptor, that is associated

3092

# with this metric type can only be associated with one of the monitored

3093

# resource types listed here.

3094

"A String",

3095

],

3096

"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.

3097

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

3098

# periodically, consecutive data points are stored at this time interval,

3099

# excluding data loss due to errors. Metrics with a higher granularity have

3100

# a smaller sampling period.

3101

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

3102

# age are guaranteed to be ingested and available to be read, excluding

3103

# data loss due to errors.

3104

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3105

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3106

"name": "A String", # The resource name of the metric descriptor.

3107

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

3108

# Some combinations of `metric_kind` and `value_type` might not be supported.

3109

"launchStage": "A String", # Optional. The launch stage of the metric definition.

3110

"type": "A String", # The metric type, including its DNS name prefix. The type is not

3111

# URL-encoded.

3112

#

3113

# All service defined metrics must be prefixed with the service name, in the

3114

# format of `{service name}/{relative metric name}`, such as

3115

# `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric

3116

# name must follow:

3117

#

3118

# * Only upper and lower-case letters, digits, '/' and underscores '_' are

3119

# allowed.

3120

# * The maximum number of characters allowed for the relative_metric_name is

3121

# 100.

3122

#

3123

# All user-defined metric types have the DNS name

3124

# `custom.googleapis.com`, `external.googleapis.com`, or

3125

# `logging.googleapis.com/user/`.

3126

#

3127

# Metric types should use a natural hierarchical grouping. For example:

3128

#

3129

# "custom.googleapis.com/invoice/paid/amount"

3130

# "external.googleapis.com/prometheus/up"

3131

# "appengine.googleapis.com/http/server/response_latencies"

3132

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3133

"labels": [ # The set of labels that can be used to describe a specific

3134

# instance of this metric type.

3135

#

3136

# The label key name must follow:

3137

#

3138

# * Only upper and lower-case letters, digits and underscores (_) are

3139

# allowed.

3140

# * Label name must start with a letter or digit.

3141

# * The maximum length of a label name is 100 characters.

3142

#

3143

# For example, the

3144

# `appengine.googleapis.com/http/server/response_latencies` metric

3145

# type has a label for the HTTP response code, `response_code`, so

3146

# you can look at latencies for successful responses or just

3147

# for responses that failed.

3148

{ # A description of a label.

3149

"valueType": "A String", # The type of data that can be assigned to the label.

3150

"description": "A String", # A human-readable description for the label.

3151

"key": "A String", # The label key.

3152

},

3153

],

3154

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

3155

# Some combinations of `metric_kind` and `value_type` might not be supported.

3156

},

3157

],

3158

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3159

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3160

# Example:

3161

# <pre><code>documentation:

3162

# summary: >

3163

# The Google Calendar API gives access

3164

# to most calendar features.

3165

# pages:

3166

# - name: Overview

3167

# content: &#40;== include google/foo/overview.md ==&#41;

3168

# - name: Tutorial

3169

# content: &#40;== include google/foo/tutorial.md ==&#41;

3170

# subpages;

3171

# - name: Java

3172

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

3173

# rules:

3174

# - selector: google.calendar.Calendar.Get

3175

# description: >

3176

# ...

3177

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3182

# standard markdown features, definition lists, tables and fenced

3183

# code blocks are supported. Section headers can be provided and are

3184

# interpreted relative to the section nesting of the context where

3185

# a documentation fragment is embedded.

3186

#

3187

# Documentation from the IDL is merged with documentation defined

3188

# via the config at normalization time, where documentation provided

3189

# by config rules overrides IDL provided.

3190

#

3191

# A number of constructs specific to the API platform are supported

3192

# in documentation text.

3193

#

3194

# In order to reference a proto element, the following

3195

# notation can be used:

3196

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

3197

# To override the display text used for the link, this can be used:

3198

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

3199

# Text can be excluded from doc using the following notation:

3200

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

3201

#

3202

# A few directives are available in documentation. Note that

3203

# directives must appear on a single line to be properly

3204

# identified. The `include` directive includes a markdown file from

3205

# an external source:

3206

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

3207

# The `resource_for` directive marks a message to be the resource of

3208

# a collection in REST view. If it is not specified, tools attempt

3209

# to infer the resource from the operations in a collection:

3210

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

3211

# The directive `suppress_warning` does not directly affect documentation

3212

# and is documented together with service config validation.

3213

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

3214

# from the yaml file) is not suitable. This can be seen in any fully

3215

# specified service urls as well as sections that show a base that other

3216

# urls are relative to.

3217

"overview": "A String", # Declares a single overview page. For example:

3218

# <pre><code>documentation:

3219

# summary: ...

3220

# overview: &#40;== include overview.md ==&#41;

3221

# </code></pre>

3222

# This is a shortcut for the following declaration (using pages style):

3223

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

3228

# </code></pre>

3229

# Note: you cannot specify both `overview` field and `pages` field.

3230

"documentationRootUrl": "A String", # The URL to the root of documentation.

3231

"rules": [ # A list of documentation rules that apply to individual API elements.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3232

#

3233

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3234

{ # A documentation rule provides information about individual API elements.

3235

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

3236

# an element is marked as `deprecated`.

3237

"description": "A String", # Description of the selected API(s).

3238

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3239

# qualified name of the element which may end in "*", indicating a wildcard.

3240

# Wildcards are only allowed at the end and for a whole component of the

3241

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

3242

# wildcard will match one or more components. To specify a default for all

3243

# applicable elements, the whole pattern "*" is used.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3244

},

3245

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3246

"pages": [ # The top level pages for the documentation set.

3247

{ # Represents a documentation page. A page can contain subpages to represent

3248

# nested documentation set structure.

3249

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

3250

# ==&#41;</code> to include content from a Markdown file.

3251

"name": "A String", # The name of the page. It will be used as an identity of the page to

3252

# generate URI of the page, text of the link to this page in navigation,

3253

# etc. The full page name (start from the root page name to this page

3254

# concatenated with `.`) can be used as reference to the page in your

3255

# documentation. For example:

3256

# <pre><code>pages:

3257

# - name: Tutorial

3258

# content: &#40;== include tutorial.md ==&#41;

3259

# subpages:

3260

# - name: Java

3261

# content: &#40;== include tutorial_java.md ==&#41;

3262

# </code></pre>

3263

# You can reference `Java` page using Markdown reference link syntax:

3264

# `Java`.

3265

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3266

# honored in the generated docset.

3267

# Object with schema name: Page

],

},

],

"summary": "A String", # A short summary of what the service does. Can only be provided by

3272

# plain text.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3273

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3274

"configVersion": 42, # The semantic version of the service configuration. The config version

3275

# affects the interpretation of the service configuration. For example,

3276

# certain features are enabled by default for certain config versions.

3277

#

3278

# The latest config version is `3`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3279

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

3280

# usage.

3281

#

3282

# The metric based quota configuration works this way:

3283

# - The service configuration defines a set of metrics.

3284

# - For API calls, the quota.metric_rules maps methods to metrics with

3285

# corresponding costs.

3286

# - The quota.limits defines limits on the metrics, which will be used for

3287

# quota checks at runtime.

3288

#

3289

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

3295

# metric: library.googleapis.com/write_calls

3296

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

3302

# # except for the UpdateBook and DeleteBook methods. These two methods

3303

# # are mapped to the write_calls metric, with the UpdateBook method

3304

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

3309

# - selector: google.example.library.v1.LibraryService.UpdateBook

3310

# metric_costs:

3311

# library.googleapis.com/write_calls: 2

3312

# - selector: google.example.library.v1.LibraryService.DeleteBook

3313

# metric_costs:

3314

# library.googleapis.com/write_calls: 1

3315

#

3316

# Corresponding Metric definition:

3317

#

3318

# metrics:

3319

# - name: library.googleapis.com/read_calls

3320

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

3325

# display_name: Write requests

3326

# metric_kind: DELTA

3327

# value_type: INT64

3328

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3329

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

3330

# or more metrics.

3331

{ # Bind API methods to metrics. Binding a method to a metric causes that

3332

# metric's configured quota behaviors to apply to the method call.

3333

"selector": "A String", # Selects the methods to which this rule applies.

3334

#

3335

# Refer to selector for syntax details.

3336

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

3337

# cost applied to each metric.

3338

#

3339

# The key of the map is the metric name, and the values are the amount

3340

# increased for the metric against which the quota limits are defined.

3341

# The value must not be negative.

"a_key": "A String",

},

},

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3346

"limits": [ # List of `QuotaLimit` definitions for the service.

3347

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

3348

# for a limit type. There can be at most one limit for a duration and limit

3349

# type combination defined within a `QuotaGroup`.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3350

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

3351

# integer value that is the maximum number of requests allowed for the

3352

# specified unit. Currently only STANDARD is supported.

3353

"a_key": "A String",

3354

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3355

"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]

3356

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3357

# Used by group-based quotas only.

3358

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

3359

# The free tier is the number of tokens that will be subtracted from the

3360

# billed amount when billing is enabled.

3361

# This field can only be set on a limit with duration "1d", in a billable

3362

# group; it is invalid on any other limit. If this field is not set, it

3363

# 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]

3364

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3365

# Used by group-based quotas only.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3366

"displayName": "A String", # User-visible display name for this limit.

3367

# Optional. If not set, the UI will provide a default display name based on

3368

# the quota configuration. This field can be used to override the default

3369

# display name generated from the configuration.

3370

"description": "A String", # Optional. User-visible, extended description for this quota limit.

3371

# Should be used only when more context is needed to understand this limit

3372

# than provided by the limit's display name (see: `display_name`).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3373

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

3374

# duration. This is the number of tokens assigned when a client

3375

# application developer activates the service for his/her project.

3376

#

3377

# Specifying a value of 0 will block all requests. This can be used if you

3378

# are provisioning quota to selected consumers and blocking others.

3379

# Similarly, a value of -1 will indicate an unlimited quota. No other

3380

# negative values are allowed.

3381

#

3382

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3383

"name": "A String", # Name of the quota limit.

3384

#

3385

# The name must be provided, and it must be unique within the service. The

3386

# name can only include alphanumeric characters as well as '-'.

3387

#

3388

# The maximum length of the limit name is 64 characters.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3389

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

3390

# duration. Client application developers can override the default limit up

3391

# to this maximum. If specified, this value cannot be set to a value less

3392

# than the default limit. If not specified, it is set to the default limit.

3393

#

3394

# To allow clients to apply overrides with no upper bound, set this to -1,

3395

# indicating unlimited maximum quota.

3396

#

3397

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3398

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

3399

# the same metric will be checked together during runtime. The metric must be

3400

# defined within the service config.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3401

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

3402

# Metric.unit. The supported unit kinds are determined by the quota

3403

# backend system.

3404

#

3405

# Here are some examples:

3406

# * "1/min/{project}" for quota per minute per project.

3407

#

3408

# Note: the order of unit components is insignificant.

3409

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3410

},

3411

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3412

},

3413

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3414

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3422

# - google.foo.v1.AnotherError

3423

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

3424

"A String",

3425

],

3426

"rules": [ # The list of custom error rules that apply to individual API messages.

3427

#

3428

# **NOTE:** All service configuration rules follow "last one wins" order.

3429

{ # A custom error rule.

3430

"selector": "A String", # Selects messages to which this rule applies.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3431

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3432

# Refer to selector for syntax details.

3433

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3434

# objects of this type will be filtered when they appear in error payload.

},

],

},

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3439

#

3440

# Example for an API targeted for external use:

3441

#

3442

# name: calendar.googleapis.com

3443

# authentication:

3444

# providers:

3445

# - id: google_calendar_auth

3446

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3447

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

3452

"rules": [ # A list of authentication rules that apply to individual API methods.

3453

#

3454

# **NOTE:** All service configuration rules follow "last one wins" order.

3455

{ # Authentication rules for the service.

3456

#

3457

# By default, if a method has any authentication requirements, every request

3458

# must include a valid credential matching one of the requirements.

3459

# It's an error to include more than one kind of credential in a single

3460

# request.

3461

#

3462

# If a method doesn't have any auth requirements, request credentials will be

3463

# ignored.

3464

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3465

# there are scopes defined for "Read-only access to Google Calendar" and

3466

# "Access to Cloud Platform". Users can consent to a scope for an application,

3467

# giving it permission to access that data on their behalf.

3468

#

3469

# OAuth scope specifications should be fairly coarse grained; a user will need

3470

# to see and understand the text description of what your scope means.

3471

#

3472

# In most cases: use one or at most two OAuth scopes for an entire family of

3473

# products. If your product has multiple APIs, you should probably be sharing

3474

# the OAuth scope across all of those APIs.

3475

#

3476

# When you need finer grained OAuth consent screens: talk with your product

3477

# management about how developers will use them in practice.

3478

#

3479

# Please note that even though each of the canonical scopes is enough for a

3480

# request to be accepted and passed to the backend, a request can still fail

3481

# due to the backend requiring additional scopes or permissions.

3482

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3483

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3488

# https://www.googleapis.com/auth/calendar.read

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3489

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3490

"requirements": [ # Requirements for additional authentication providers.

3491

{ # User-defined authentication requirements, including support for

3492

# [JSON Web Token

3493

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3494

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3499

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3500

# implemented and accepted in all the runtime components.

3501

#

3502

# The list of JWT

3503

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3504

# that are allowed to access. A JWT containing any of these audiences will

3505

# be accepted. When this setting is absent, only JWTs with audience

3506

# "https://Service_name/API_name"

3507

# will be accepted. For example, if no audiences are in the setting,

3508

# LibraryService API will only accept JWTs with the following audience

3509

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3514

# bookstore_web.apps.googleusercontent.com

3515

},

3516

],

3517

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3518

"selector": "A String", # Selects the methods to which this rule applies.

3519

#

3520

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3521

},

3522

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3523

"providers": [ # Defines a set of authentication providers that a service supports.

3524

{ # Configuration for an authentication provider, including support for

3525

# [JSON Web Token

3526

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3527

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3528

# `AuthRequirement.provider_id`.

3529

#

3530

# Example: "bookstore_auth".

3531

"issuer": "A String", # Identifies the principal that issued the JWT. See

3532

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3533

# Usually a URL or an email address.

3534

#

3535

# Example: https://securetoken.google.com

3536

# Example: 1234567-compute@developer.gserviceaccount.com

3537

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3538

# [OpenID

3539

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3540

# Optional if the key set document:

3541

# - can be retrieved from

3542

# [OpenID

3543

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

3544

# the issuer.

3545

# - can be inferred from the email domain of the issuer (e.g. a Google

3546

# service account).

3547

#

3548

# Example: https://www.googleapis.com/oauth2/v1/certs

3549

"audiences": "A String", # The list of JWT

3550

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3551

# that are allowed to access. A JWT containing any of these audiences will

3552

# be accepted. When this setting is absent, JWTs with audiences:

3553

# - "https://[service.name]/[google.protobuf.Api.name]"

3554

# - "https://[service.name]/"

3555

# will be accepted.

3556

# For example, if no audiences are in the setting, LibraryService API will

3557

# accept JWTs with the following audiences:

3558

# -

3559

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

3560

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3565

# bookstore_web.apps.googleusercontent.com

3566

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

3567

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

3568

"jwtLocations": [ # Defines the locations to extract the JWT.

3569

#

3570

# JWT locations can be either from HTTP headers or URL query parameters.

3571

# The rule is that the first match wins. The checking order is: checking

3572

# all headers first, then URL query parameters.

3573

#

3574

# If not specified, default to use following 3 locations:

3575

# 1) Authorization: Bearer

3576

# 2) x-goog-iap-jwt-assertion

3577

# 3) access_token query parameter

3578

#

3579

# Default locations can be specified as followings:

3580

# jwt_locations:

3581

# - header: Authorization

3582

# value_prefix: "Bearer "

3583

# - header: x-goog-iap-jwt-assertion

3584

# - query: access_token

3585

{ # Specifies a location to extract JWT from an API request.

3586

"query": "A String", # Specifies URL query parameter name to extract JWT token.

3587

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

3588

# Only applies to "in" header type. Must be empty for "in" query type.

3589

# If not empty, the header value has to match (case sensitive) this prefix.

3590

# If not matched, JWT will not be extracted. If matched, JWT will be

3591

# extracted after the prefix is removed.

3592

#

3593

# For example, for "Authorization: Bearer {JWT}",

3594

# value_prefix="Bearer " with a space at the end.

3595

"header": "A String", # Specifies HTTP header name to extract JWT token.

},

],

},

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3600

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3601

"title": "A String", # The product title for this service.

3602

"producerProjectId": "A String", # The Google project that owns this service.

3603

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3604

# of the google.protobuf.Api needs to be provided by the configuration

3605

# author, as the remaining fields will be derived from the IDL during the

3606

# normalization process. It is an error to specify an API interface here

3607

# which cannot be resolved against the associated IDL files.

3608

{ # Api is a light-weight descriptor for an API Interface.

3609

#

3610

# Interfaces are also described as "protocol buffer services" in some contexts,

3611

# such as by the "service" keyword in a .proto file, but they are different

3612

# from API Services, which represent a concrete implementation of an interface

3613

# as opposed to simply a description of methods and bindings. They are also

3614

# sometimes simply referred to as "APIs" in other contexts, such as the name of

3615

# this message itself. See https://cloud.google.com/apis/design/glossary for

3616

# detailed terminology.

3617

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

3618

# message.

3619

# protobuf element, like the file in which it is defined.

3620

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3621

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3622

},

3623

"syntax": "A String", # The source syntax of the service.

3624

"methods": [ # The methods of this interface, in unspecified order.

3625

{ # Method represents a method of an API interface.

3626

"options": [ # Any metadata attached to the method.

3627

{ # A protocol buffer option, which can be attached to a message, field,

3628

# enumeration, etc.

3629

"value": { # The option's value packed in an Any message. If the value is a primitive,

3630

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3631

# should be used. If the value is an enum, it should be stored as an int32

3632

# value using the google.protobuf.Int32Value type.

3633

"a_key": "", # Properties of the object. Contains field @type with type URL.

3634

},

3635

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3636

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3637

# For custom options, it should be the fully-qualified name. For example,

3638

# `"google.api.http"`.

3639

},

3640

],

3641

"responseStreaming": True or False, # If true, the response is streamed.

3642

"syntax": "A String", # The source syntax of this method.

3643

"requestTypeUrl": "A String", # A URL of the input message type.

3644

"name": "A String", # The simple name of this method.

3645

"responseTypeUrl": "A String", # The URL of the output message type.

3646

"requestStreaming": True or False, # If true, the request is streamed.

3647

},

3648

],

3649

"name": "A String", # The fully qualified name of this interface, including package name

3650

# followed by the interface's simple name.

3651

"version": "A String", # A version string for this interface. If specified, must have the form

3652

# `major-version.minor-version`, as in `1.10`. If the minor version is

3653

# omitted, it defaults to zero. If the entire version field is empty, the

3654

# major version is derived from the package name, as outlined below. If the

3655

# field is not empty, the version in the package name will be verified to be

3656

# consistent with what is provided here.

3657

#

3658

# The versioning schema uses [semantic

3659

# versioning](http://semver.org) where the major version number

3660

# indicates a breaking change and the minor version an additive,

3661

# non-breaking change. Both version numbers are signals to users

3662

# what to expect from different versions, and should be carefully

3663

# chosen based on the product plan.

3664

#

3665

# The major version is also reflected in the package name of the

3666

# interface, which must end in `v<major-version>`, as in

3667

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3668

# be omitted. Zero major versions must only be used for

3669

# experimental, non-GA interfaces.

3670

"options": [ # Any metadata attached to the interface.

3671

{ # A protocol buffer option, which can be attached to a message, field,

3672

# enumeration, etc.

3673

"value": { # The option's value packed in an Any message. If the value is a primitive,

3674

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3675

# should be used. If the value is an enum, it should be stored as an int32

3676

# value using the google.protobuf.Int32Value type.

3677

"a_key": "", # Properties of the object. Contains field @type with type URL.

3678

},

3679

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3680

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3681

# For custom options, it should be the fully-qualified name. For example,

3682

# `"google.api.http"`.

3683

},

3684

],

3685

"mixins": [ # Included interfaces. See Mixin.

3686

{ # Declares an API Interface to be included in this interface. The including

3687

# interface must redeclare all the methods from the included interface, but

3688

# documentation and options are inherited as follows:

3689

#

3690

# - If after comment and whitespace stripping, the documentation

3691

# string of the redeclared method is empty, it will be inherited

3692

# from the original method.

3693

#

3694

# - Each annotation belonging to the service config (http,

3695

# visibility) which is not set in the redeclared method will be

3696

# inherited.

3697

#

3698

# - If an http annotation is inherited, the path pattern will be

3699

# modified as follows. Any version prefix will be replaced by the

3700

# version of the including interface plus the root path if

3701

# specified.

3702

#

3703

# Example of a simple mixin:

3704

#

3705

# package google.acl.v1;

3706

# service AccessControl {

3707

# // Get the underlying ACL object.

3708

# rpc GetAcl(GetAclRequest) returns (Acl) {

3709

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3714

# service Storage {

3715

# // rpc GetAcl(GetAclRequest) returns (Acl);

3716

#

3717

# // Get a data record.

3718

# rpc GetData(GetDataRequest) returns (Data) {

3719

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3724

#

3725

# apis:

3726

# - name: google.storage.v2.Storage

3727

# mixins:

3728

# - name: google.acl.v1.AccessControl

3729

#

3730

# The mixin construct implies that all methods in `AccessControl` are

3731

# also declared with same name and request/response types in

3732

# `Storage`. A documentation generator or annotation processor will

3733

# see the effective `Storage.GetAcl` method after inherting

3734

# documentation and annotations as follows:

3735

#

3736

# service Storage {

3737

# // Get the underlying ACL object.

3738

# rpc GetAcl(GetAclRequest) returns (Acl) {

3739

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3745

#

3746

# If the `root` field in the mixin is specified, it should be a

3747

# relative path under which inherited HTTP paths are placed. Example:

3748

#

3749

# apis:

3750

# - name: google.storage.v2.Storage

3751

# mixins:

3752

# - name: google.acl.v1.AccessControl

3753

# root: acls

3754

#

3755

# This implies the following inherited HTTP annotation:

3756

#

3757

# service Storage {

3758

# // Get the underlying ACL object.

3759

# rpc GetAcl(GetAclRequest) returns (Acl) {

3760

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3765

# are rooted.

3766

"name": "A String", # The fully qualified name of the interface which is included.

},

],

},

],

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3772

# by the client for tracking purpose. Must be no longer than 63 characters

3773

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

3774

# empty, the server may choose to generate one instead.

3775

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

3776

# with the same name as the service is automatically generated to service all

3777

# defined APIs.

3778

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

3779

# A service may expose any number of endpoints, and all endpoints share the

3780

# same service configuration, such as quota configuration and monitoring

3781

# configuration.

3782

#

3783

# Example service configuration:

3784

#

3785

# name: library-example.googleapis.com

3786

# endpoints:

3787

# # Below entry makes 'google.example.library.v1.Library'

3788

# # API be served from endpoint address library-example.googleapis.com.

3789

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

3790

# # it to decide whether the subsequent cross-origin request is

3791

# # allowed to proceed.

3792

# - name: library-example.googleapis.com

3793

# allow_cors: true

3794

"name": "A String", # The canonical name of this endpoint.

3795

"allowCors": True or False, # Allowing

3796

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

3797

# cross-domain traffic, would allow the backends served from this endpoint to

3798

# receive and respond to HTTP OPTIONS requests. The response will be used by

3799

# the browser to determine whether the subsequent cross-origin request is

3800

# allowed to proceed.

3801

"target": "A String", # The specification of an Internet routable address of API frontend that will

3802

# handle requests to this [API

3803

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

3804

# either a valid IPv4 address or a fully-qualified domain name. For example,

3805

# "8.8.8.8" or "myservice.appspot.com".

3806

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

3807

# please specify multiple google.api.Endpoint for each of the intended

3808

# aliases.

3809

#

3810

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3816

#

3817

# A system parameter is a special kind of parameter defined by the API

3818

# system, not by an individual API. It is typically mapped to an HTTP header

3819

# and/or a URL query parameter. This configuration specifies which methods

3820

# change the names of the system parameters.

3821

"rules": [ # Define system parameters.

3822

#

3823

# The parameters defined here will override the default parameters

3824

# implemented by the system. If this field is missing from the service

3825

# config, default system parameters will be used. Default system parameters

3826

# and names is implementation-dependent.

3827

#

3828

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3836

#

3837

#

3838

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3843

# parameters:

3844

# - name: api_key

3845

# http_header: Api-Key1

3846

# - name: api_key

3847

# http_header: Api-Key2

3848

#

3849

# **NOTE:** All service configuration rules follow "last one wins" order.

3850

{ # Define a system parameter rule mapping system parameter definitions to

3851

# methods.

3852

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3853

# For a given method call, only one of them should be used. If multiple

3854

# names are used the behavior is implementation-dependent.

3855

# If none of the specified names are present the behavior is

3856

# parameter-dependent.

3857

{ # Define a parameter's name and location. The parameter may be passed as either

3858

# an HTTP header or a URL query parameter, and if both are passed the behavior

3859

# is implementation-dependent.

3860

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3861

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

3862

# insensitive.

3863

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

# sensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3868

# methods in all APIs.

3869

#

3870

# Refer to selector for syntax details.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3875

# by the Service.monitoring and Service.logging configurations.

3876

{ # An object that describes the schema of a MonitoredResource object using a

3877

# type name and a set of labels. For example, the monitored resource

3878

# descriptor for Google Compute Engine VM instances has a type of

3879

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3880

# `"zone"` to identify particular VM instances.

3881

#

3882

# Different services can support different monitored resource types.

3883

#

3884

# The following are specific rules to service defined monitored resources for

3885

# Monitoring and Logging:

3886

#

3887

# * The `type`, `display_name`, `description`, `labels` and `launch_stage`

3888

# fields are all required.

3889

# * The first label of the monitored resource descriptor must be

3890

# `resource_container`. There are legacy monitored resource descritptors

3891

# start with `project_id`.

3892

# * It must include a `location` label.

3893

# * Maximum of default 5 service defined monitored resource descriptors

3894

# is allowed per service.

3895

# * Maximum of default 10 labels per monitored resource is allowed.

3896

#

3897

# The default maximum limit can be overridden. Please follow

3898

# https://cloud.google.com/monitoring/quotas

3899

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3900

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3901

# {type} is the value of the `type` field in this object and

3902

# {project_id} is a project ID that provides API-specific context for

3903

# accessing the type. APIs that do not use project information can use the

3904

# resource name format `"monitoredResourceDescriptors/{type}"`.

3905

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

3906

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3907

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3908

# without any article or other determiners. For example,

3909

# `"Google Cloud SQL Database"`.

3910

"labels": [ # Required. A set of labels used to describe instances of this monitored

3911

# resource type.

3912

# The label key name must follow:

3913

#

3914

# * Only upper and lower-case letters, digits and underscores (_) are

3915

# allowed.

3916

# * Label name must start with a letter or digit.

3917

# * The maximum length of a label name is 100 characters.

3918

#

3919

# For example, an individual Google Cloud SQL database is

3920

# identified by values for the labels `database_id` and `location`.

3921

{ # A description of a label.

3922

"valueType": "A String", # The type of data that can be assigned to the label.

3923

"description": "A String", # A human-readable description for the label.

3924

"key": "A String", # The label key.

3925

},

3926

],

3927

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3928

# be used in documentation.

3929

"type": "A String", # Required. The monitored resource type. For example, the type

3930

# `cloudsql_database` represents databases in Google Cloud SQL.

3931

#

3932

# All service defined monitored resource types must be prefixed with the

3933

# service name, in the format of `{service name}/{relative resource name}`.

3934

# The relative resource name must follow:

3935

#

3936

# * Only upper and lower-case letters and digits are allowed.

3937

# * It must start with upper case character and is recommended to use Upper

3938

# Camel Case style.

3939

# * The maximum number of characters allowed for the relative_resource_name

3940

# is 100.

3941

#

3942

# Note there are legacy service monitored resources not following this rule.

3943

},

3944

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3945

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3946

#

3947

# Example:

3948

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

3954

# - google.rpc.context.OriginContext

3955

#

3956

# The above specifies that all methods in the API request

3957

# `google.rpc.context.ProjectContext` and

3958

# `google.rpc.context.OriginContext`.

3959

#

3960

# Available context types are defined in package

3961

# `google.rpc.context`.

3962

#

3963

# This also provides mechanism to whitelist any protobuf message extension that

3964

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

3965

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

3966

# 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"

3974

# allowed_request_extensions:

3975

# - google.foo.v1.NewExtension

3976

# allowed_response_extensions:

3977

# - google.foo.v1.NewExtension

3978

#

3979

# You can also specify extension ID instead of fully qualified extension name

3980

# here.

3981

"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]

3982

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3983

# **NOTE:** All service configuration rules follow "last one wins" order.

3984

{ # A context rule provides information about the context for an individual API

3985

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3986

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3987

#

3988

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

3989

"requested": [ # A list of full type names of requested contexts.

3990

"A String",

3991

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

3992

"provided": [ # A list of full type names of provided contexts.

3993

"A String",

3994

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

3995

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3996

# side channel from client to backend.

3997

"A String",

3998

],

3999

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

4000

# side channel from backend to client.

4001

"A String",

4002

],

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]

4010

<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]

4011

<pre>Gets a service configuration (version) for a managed service.

4012

4013

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4014

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]

4015

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4016

configId: string, Required. The id of the service configuration resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4017

4018

This field must be specified for the server to return all fields, including

4019

`SourceInfo`. (required)

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4020

view: string, Specifies which parts of the Service Config should be returned in the

4021

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4022

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4029

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4030

{ # `Service` is the root object of Google service configuration schema. It

4031

# describes basic information about a service, such as the name and the

4032

# title, and delegates other aspects to sub-sections. Each sub-section is

4033

# either a proto message or a repeated proto message that configures a

4034

# 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]

4039

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4040

# name: calendar.googleapis.com

4041

# title: Google Calendar API

4042

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4043

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4044

# authentication:

4045

# providers:

4046

# - id: google_calendar_auth

4047

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4048

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4049

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4050

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4051

# requirements:

4052

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4053

"enums": [ # A list of all enum types included in this API service. Enums

4054

# referenced directly or indirectly by the `apis` are automatically

4055

# included. Enums which are not referenced but shall be included

4056

# should be listed here by name. Example:

4057

#

4058

# enums:

4059

# - name: google.someapi.v1.SomeEnum

4060

{ # Enum type definition.

4061

"options": [ # Protocol buffer options.

4062

{ # A protocol buffer option, which can be attached to a message, field,

4063

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4064

"value": { # The option's value packed in an Any message. If the value is a primitive,

4065

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4066

# should be used. If the value is an enum, it should be stored as an int32

4067

# value using the google.protobuf.Int32Value type.

4068

"a_key": "", # Properties of the object. Contains field @type with type URL.

4069

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4070

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4071

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4072

# For custom options, it should be the fully-qualified name. For example,

4073

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4074

},

4075

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4076

"enumvalue": [ # Enum value definitions.

4077

{ # Enum value definition.

4078

"name": "A String", # Enum value name.

4079

"options": [ # Protocol buffer options.

4080

{ # A protocol buffer option, which can be attached to a message, field,

4081

# enumeration, etc.

4082

"value": { # The option's value packed in an Any message. If the value is a primitive,

4083

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4084

# should be used. If the value is an enum, it should be stored as an int32

4085

# value using the google.protobuf.Int32Value type.

4086

"a_key": "", # Properties of the object. Contains field @type with type URL.

4087

},

4088

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4089

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4090

# For custom options, it should be the fully-qualified name. For example,

4091

# `"google.api.http"`.

4092

},

4093

],

4094

"number": 42, # Enum value number.

4095

},

4096

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4097

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4098

# protobuf element, like the file in which it is defined.

4099

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4100

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4101

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4102

"name": "A String", # Enum type name.

4103

"syntax": "A String", # The source syntax.

4104

},

4105

],

4106

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4107

"rules": [ # A list of API backend rules that apply to individual API methods.

4108

#

4109

# **NOTE:** All service configuration rules follow "last one wins" order.

4110

{ # A backend rule provides configuration for an individual API element.

4111

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

4112

# original "Authorization" HTTP header will be preserved. If the header is

4113

# used to carry the original token and is expected by the backend, this

4114

# field must be set to true to preserve the header.

4115

"address": "A String", # The address of the API backend.

4116

#

4117

# The scheme is used to determine the backend protocol and security.

4118

# The following schemes are accepted:

4119

#

4120

# 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

4127

# may cause constrasting behaviors across platforms.

4128

#

4129

# If the port is unspecified, the default is:

4130

# - 80 for schemes without TLS

4131

# - 443 for schemes with TLS

4132

#

4133

# For HTTP backends, use protocol

4134

# to specify the protocol version.

4135

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

4136

# value lower than this will be rejected.

4137

"selector": "A String", # Selects the methods to which this rule applies.

4138

#

4139

# Refer to selector for syntax details.

4140

"protocol": "A String", # The protocol used for sending a request to the backend.

4141

# The supported values are "http/1.1" and "h2".

4142

#

4143

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

4153

# to "h2" for improved performance.

4154

#

4155

# Configuring this field to non-default values is only supported for secure

4156

# HTTP backends. This field will be ignored for all other backends.

4157

#

4158

# See

4159

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

4160

# for more details on the supported values.

4161

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

4162

# operation. The default is no deadline.

4163

"pathTranslation": "A String",

4164

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

4165

# This ID token will be added in the HTTP "authorization" header, and sent

4166

# to the backend.

4167

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

4168

# varies based on the request protocol and deployment environment.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

4173

# It serves similar purpose as [google.api.Service.types], except that

4174

# these types are not needed by user-defined APIs. Therefore, they will not

4175

# show up in the generated discovery doc. This field should only be used

4176

# to define system APIs in ESF.

4177

{ # A protocol buffer message type.

4178

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4179

# protobuf element, like the file in which it is defined.

4180

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4181

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4182

},

4183

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4184

"A String",

4185

],

4186

"fields": [ # The list of fields.

4187

{ # A single field of a message type.

4188

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4189

# types. The first type has index 1; zero means the type is not in the list.

4190

"name": "A String", # The field name.

4191

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4192

"packed": True or False, # Whether to use alternative packed wire representation.

4193

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4194

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4195

"cardinality": "A String", # The field cardinality.

4196

"jsonName": "A String", # The field JSON name.

4197

"kind": "A String", # The field type.

4198

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4199

{ # A protocol buffer option, which can be attached to a message, field,

4200

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4201

"value": { # The option's value packed in an Any message. If the value is a primitive,

4202

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4203

# should be used. If the value is an enum, it should be stored as an int32

4204

# value using the google.protobuf.Int32Value type.

4205

"a_key": "", # Properties of the object. Contains field @type with type URL.

4206

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4207

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4208

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4209

# For custom options, it should be the fully-qualified name. For example,

4210

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4211

},

4212

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4213

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4214

},

4215

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4216

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4217

{ # A protocol buffer option, which can be attached to a message, field,

4218

# enumeration, etc.

4219

"value": { # The option's value packed in an Any message. If the value is a primitive,

4220

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4221

# should be used. If the value is an enum, it should be stored as an int32

4222

# value using the google.protobuf.Int32Value type.

4223

"a_key": "", # Properties of the object. Contains field @type with type URL.

4224

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4225

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4226

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4227

# For custom options, it should be the fully-qualified name. For example,

4228

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4229

},

4230

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4231

"syntax": "A String", # The source syntax.

4232

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4233

},

4234

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4235

"name": "A String", # The service name, which is a DNS-like logical identifier for the

4236

# service, such as `calendar.googleapis.com`. The service name

4237

# typically goes through DNS verification to make sure the owner

4238

# of the service also owns the DNS name.

4239

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

4240

"sourceFiles": [ # All files used during config generation.

4241

{

4242

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4243

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4244

],

4245

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4246

"billing": { # Billing related configuration of the service. # Billing configuration.

4247

#

4248

# The following example shows how to configure monitored resources and metrics

4249

# for billing, `consumer_destinations` is the only supported destination and

4250

# the monitored resources need at least one label key

4251

# `cloud.googleapis.com/location` to indicate the location of the billing

4252

# usage, using different monitored resources between monitoring and billing is

4253

# recommended so they can be evolved independently:

4254

#

4255

#

4256

# monitored_resources:

4257

# - type: library.googleapis.com/billing_branch

4258

# labels:

4259

# - key: cloud.googleapis.com/location

4260

# description: |

4261

# Predefined label to support billing location restriction.

4262

# - key: city

4263

# description: |

4264

# Custom label to define the city where the library branch is located

4265

# in.

4266

# - key: name

4267

# description: Custom label to define the name of the library branch.

4268

# metrics:

4269

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

4275

# - monitored_resource: library.googleapis.com/billing_branch

4276

# metrics:

4277

# - library.googleapis.com/book/borrowed_count

4278

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

4279

# There can be multiple consumer destinations per service, each one must have

4280

# a different monitored resource type. A metric can be used in at most

4281

# one consumer destination.

4282

{ # Configuration of a specific billing destination (Currently only support

4283

# bill against consumer project).

4284

"metrics": [ # Names of the metrics to report to this billing destination.

4285

# Each name must be defined in Service.metrics section.

4286

"A String",

4287

],

4288

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4289

# Service.monitored_resources section.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

4294

#

4295

# The example below shows how to configure monitored resources and metrics

4296

# for monitoring. In the example, a monitored resource and two metrics are

4297

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4298

# to both producer and consumer projects, whereas the

4299

# `library.googleapis.com/book/num_overdue` metric is only sent to the

4300

# consumer project.

4301

#

4302

# monitored_resources:

4303

# - type: library.googleapis.com/Branch

4304

# display_name: "Library Branch"

4305

# description: "A branch of a library."

4306

# launch_stage: GA

4307

# labels:

4308

# - key: resource_container

4309

# description: "The Cloud container (ie. project id) for the Branch."

4310

# - key: location

4311

# description: "The location of the library branch."

4312

# - key: branch_id

4313

# description: "The id of the branch."

4314

# metrics:

4315

# - name: library.googleapis.com/book/returned_count

4316

# display_name: "Books Returned"

4317

# description: "The count of books that have been returned."

# launch_stage: GA

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

4325

# - name: library.googleapis.com/book/num_overdue

4326

# display_name: "Books Overdue"

4327

# description: "The current number of overdue books."

# launch_stage: GA

# metric_kind: GAUGE

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

4335

# monitoring:

4336

# producer_destinations:

4337

# - monitored_resource: library.googleapis.com/Branch

4338

# metrics:

4339

# - library.googleapis.com/book/returned_count

4340

# consumer_destinations:

4341

# - monitored_resource: library.googleapis.com/Branch

4342

# metrics:

4343

# - library.googleapis.com/book/returned_count

4344

# - library.googleapis.com/book/num_overdue

4345

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4346

# There can be multiple producer destinations. A monitored resource type may

4347

# appear in multiple monitoring destinations if different aggregations are

4348

# needed for different sets of metrics associated with that monitored

4349

# resource type. A monitored resource and metric pair may only be used once

4350

# in the Monitoring configuration.

4351

{ # Configuration of a specific monitoring destination (the producer project

4352

# or the consumer project).

4353

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4354

# Service.monitored_resources section.

4355

"metrics": [ # Types of the metrics to report to this monitoring destination.

4356

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4362

# There can be multiple consumer destinations. A monitored resource type may

4363

# appear in multiple monitoring destinations if different aggregations are

4364

# needed for different sets of metrics associated with that monitored

4365

# resource type. A monitored resource and metric pair may only be used once

4366

# in the Monitoring configuration.

4367

{ # Configuration of a specific monitoring destination (the producer project

4368

# or the consumer project).

4369

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4370

# Service.monitored_resources section.

4371

"metrics": [ # Types of the metrics to report to this monitoring destination.

4372

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"logging": { # Logging configuration of the service. # Logging configuration.

4379

#

4380

# The following example shows how to configure logs to be sent to the

4381

# producer and consumer projects. In the example, the `activity_history`

4382

# log is sent to both the producer and consumer projects, whereas the

4383

# `purchase_history` log is only sent to the producer project.

4384

#

4385

# monitored_resources:

4386

# - type: library.googleapis.com/branch

4387

# labels:

4388

# - key: /city

4389

# description: The city where the library branch is located in.

4390

# - key: /name

4391

# description: The name of the branch.

4392

# logs:

4393

# - name: activity_history

4394

# labels:

4395

# - key: /customer_id

4396

# - name: purchase_history

4397

# logging:

4398

# producer_destinations:

4399

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

4404

# - monitored_resource: library.googleapis.com/branch

4405

# logs:

4406

# - activity_history

4407

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4408

# There can be multiple producer destinations, each one must have a

4409

# different monitored resource type. A log can be used in at most

4410

# one producer destination.

4411

{ # Configuration of a specific logging destination (the producer project

4412

# or the consumer project).

4413

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

4414

# Service.monitored_resources section.

4415

"logs": [ # Names of the logs to be sent to this destination. Each name must

4416

# be defined in the Service.logs section. If the log name is

4417

# not a domain scoped name, it will be automatically prefixed with

4418

# the service name followed by "/".

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

4424

# There can be multiple consumer destinations, each one must have a

4425

# different monitored resource type. A log can be used in at most

4426

# one consumer destination.

4427

{ # Configuration of a specific logging destination (the producer project

4428

# or the consumer project).

4429

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

4430

# Service.monitored_resources section.

4431

"logs": [ # Names of the logs to be sent to this destination. Each name must

4432

# be defined in the Service.logs section. If the log name is

4433

# not a domain scoped name, it will be automatically prefixed with

4434

# the service name followed by "/".

"A String",

],

},

],

},

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4441

# service controller handles features like abuse, quota, billing, logging,

4442

# monitoring, etc.

4443

"environment": "A String", # The service control environment to use. If empty, no control plane

4444

# feature (like quota and billing) will be enabled.

4445

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4446

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4447

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4448

# service. Each requirement is of the form <service.name>/<requirement-id>;

4449

# for example 'serviceusage.googleapis.com/billing-enabled'.

4450

"A String",

4451

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4452

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

4453

#

4454

#

4455

# Use this field to configure per-product per-project service identity.

4456

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

4461

# display_name: "Cloud XXX Service Agent"

4462

# description: "Used as the identity of Cloud XXX to access resources"

4463

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

4464

#

4465

# An example name would be:

4466

# `projects/123456789`

4467

"description": "A String", # Optional. A user-specified opaque description of the service account.

4468

# Must be less than or equal to 256 UTF-8 bytes.

4469

"displayName": "A String", # Optional. A user-specified name for the service account.

4470

# Must be less than or equal to 100 UTF-8 bytes.

4471

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4472

"rules": [ # A list of usage rules that apply to individual API methods.

4473

#

4474

# **NOTE:** All service configuration rules follow "last one wins" order.

4475

{ # Usage configuration rules for the service.

4476

#

4477

# NOTE: Under development.

4478

#

4479

#

4480

# Use this rule to configure unregistered calls for the service. Unregistered

4481

# calls are calls that do not contain consumer project identity.

4482

# (Example: calls that do not contain an API key).

4483

# By default, API methods do not allow unregistered calls, and each method call

4484

# must be identified by a consumer project identity. Use this rule to

4485

# allow/disallow unregistered calls.

4486

#

4487

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4493

#

4494

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4499

# allow_unregistered_calls: true

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4500

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

4501

# plane features, such as quota and billing, will not be available.

4502

# This flag is used by Google Cloud Endpoints to bypass checks for internal

4503

# methods, such as service health check methods.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4504

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4505

# methods in all APIs.

4506

#

4507

# Refer to selector for syntax details.

4508

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

4509

# that don't identify any user or application.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4510

},

4511

],

4512

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4513

# service producer.

4514

#

4515

# Google Service Management currently only supports

4516

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

4517

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

4518

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

4519

# documented in https://cloud.google.com/pubsub/docs/overview.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4520

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4521

"types": [ # A list of all proto message types included in this API service.

4522

# Types referenced directly or indirectly by the `apis` are

4523

# automatically included. Messages which are not referenced but

4524

# shall be included, such as types used by the `google.protobuf.Any` type,

4525

# should be listed here by name. Example:

4526

#

4527

# types:

4528

# - name: google.protobuf.Int32

4529

{ # A protocol buffer message type.

4530

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4531

# protobuf element, like the file in which it is defined.

4532

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4533

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4534

},

4535

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4536

"A String",

4537

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4538

"fields": [ # The list of fields.

4539

{ # A single field of a message type.

4540

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4541

# types. The first type has index 1; zero means the type is not in the list.

4542

"name": "A String", # The field name.

4543

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4544

"packed": True or False, # Whether to use alternative packed wire representation.

4545

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4546

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4547

"cardinality": "A String", # The field cardinality.

4548

"jsonName": "A String", # The field JSON name.

4549

"kind": "A String", # The field type.

4550

"options": [ # The protocol buffer options.

4551

{ # A protocol buffer option, which can be attached to a message, field,

4552

# enumeration, etc.

4553

"value": { # The option's value packed in an Any message. If the value is a primitive,

4554

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4555

# should be used. If the value is an enum, it should be stored as an int32

4556

# value using the google.protobuf.Int32Value type.

4557

"a_key": "", # Properties of the object. Contains field @type with type URL.

4558

},

4559

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4560

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4561

# For custom options, it should be the fully-qualified name. For example,

4562

# `"google.api.http"`.

4563

},

4564

],

4565

"number": 42, # The field number.

4566

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4567

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4568

"options": [ # The protocol buffer options.

4569

{ # A protocol buffer option, which can be attached to a message, field,

4570

# enumeration, etc.

4571

"value": { # The option's value packed in an Any message. If the value is a primitive,

4572

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4573

# should be used. If the value is an enum, it should be stored as an int32

4574

# value using the google.protobuf.Int32Value type.

4575

"a_key": "", # Properties of the object. Contains field @type with type URL.

4576

},

4577

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4578

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4579

# For custom options, it should be the fully-qualified name. For example,

4580

# `"google.api.http"`.

4581

},

4582

],

4583

"syntax": "A String", # The source syntax.

4584

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4585

},

4586

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4587

"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]

4588

# HttpRule, each specifying the mapping of an RPC method

4589

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4590

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

4591

# cases of single segment matches in reserved expansion, where "%2F" will be

4592

# left encoded.

4593

#

4594

# The default behavior is to not decode RFC 6570 reserved characters in multi

4595

# segment matches.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4596

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4597

#

4598

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4599

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4600

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4601

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

4602

# more HTTP REST endpoints. It allows developers to build a single API service

4603

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

4604

# APIs](https://github.com/googleapis/googleapis),

4605

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

4606

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

4607

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

4608

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4609

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4610

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

4611

# how different portions of the gRPC request message are mapped to the URL

4612

# path, URL query parameters, and HTTP request body. It also controls how the

4613

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

4614

# typically specified as an `google.api.http` annotation on the gRPC method.

4615

#

4616

# Each mapping specifies a URL path template and an HTTP method. The path

4617

# template may refer to one or more fields in the gRPC request message, as long

4618

# as each field is a non-repeated field with a primitive (non-message) type.

4619

# The path template controls how fields of the request message are mapped to

4620

# the URL path.

4621

#

4622

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4623

#

4624

# service Messaging {

4625

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4626

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4627

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4628

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4629

# }

4630

# }

4631

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4632

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4633

# }

4634

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4635

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4636

# }

4637

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4638

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4639

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4640

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4641

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4642

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4643

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4644

# Any fields in the request message which are not bound by the path template

4645

# automatically become HTTP query parameters if there is no HTTP request body.

4646

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4647

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4648

# service Messaging {

4649

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4650

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4651

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4652

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4653

# }

4654

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4655

# message GetMessageRequest {

4656

# message SubMessage {

4657

# string subfield = 1;

4658

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4659

# string message_id = 1; // Mapped to URL path.

4660

# int64 revision = 2; // Mapped to URL query parameter `revision`.

4661

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4662

# }

4663

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4664

# This enables a HTTP JSON to RPC mapping as below:

4665

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4666

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4667

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4668

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4669

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

4670

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4671

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4672

# Note that fields which are mapped to URL query parameters must have a

4673

# primitive type or a repeated primitive type or a non-repeated message type.

4674

# 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]

4675

# 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]

4676

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

4677

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4678

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4679

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4680

# specifies the mapping. Consider a REST update method on the

4681

# message resource collection:

4682

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4683

# service Messaging {

4684

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4685

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4686

# patch: "/v1/messages/{message_id}"

4687

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

4692

# string message_id = 1; // mapped to the URL

4693

# Message message = 2; // mapped to the body

4694

# }

4695

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4696

# The following HTTP JSON to RPC mapping is enabled, where the

4697

# representation of the JSON in the request body is determined by

4698

# protos JSON encoding:

4699

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4700

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4701

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4702

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4703

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4704

#

4705

# The special name `*` can be used in the body mapping to define that

4706

# every field not bound by the path template should be mapped to the

4707

# request body. This enables the following alternative definition of

4708

# the update method:

4709

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4710

# service Messaging {

4711

# rpc UpdateMessage(Message) returns (Message) {

4712

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4713

# patch: "/v1/messages/{message_id}"

4714

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

4720

# string text = 2;

4721

# }

4722

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4723

#

4724

# The following HTTP JSON to RPC mapping is enabled:

4725

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4726

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4727

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4728

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4729

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4730

#

4731

# Note that when using `*` in the body mapping, it is not possible to

4732

# 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]

4733

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4734

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4735

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4736

#

4737

# It is possible to define multiple HTTP methods for one RPC by using

4738

# the `additional_bindings` option. Example:

4739

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4740

# service Messaging {

4741

# rpc GetMessage(GetMessageRequest) returns (Message) {

4742

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4743

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4744

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4745

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4746

# }

4747

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4748

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4749

# }

4750

# message GetMessageRequest {

4751

# string message_id = 1;

4752

# string user_id = 2;

4753

# }

4754

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4755

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4756

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4757

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4758

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4759

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4760

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

4761

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4762

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4763

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4764

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4765

# 1. Leaf request fields (recursive expansion nested messages in the request

4766

# message) are classified into three categories:

4767

# - Fields referred by the path template. They are passed via the URL path.

4768

# - Fields referred by the HttpRule.body. They are passed via the HTTP

4769

# request body.

4770

# - All other fields are passed via the URL query parameters, and the

4771

# parameter name is the field path in the request message. A repeated

4772

# field can be represented as multiple query parameters under the same

4773

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4774

# 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]

4775

# are passed via URL path and HTTP request body.

4776

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

4777

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4778

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4779

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4780

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4781

# Template = "/" Segments [ Verb ] ;

4782

# Segments = Segment { "/" Segment } ;

4783

# Segment = "*" | "**" | LITERAL | Variable ;

4784

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4785

# FieldPath = IDENT { "." IDENT } ;

4786

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4787

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4788

# The syntax `*` matches a single URL path segment. The syntax `**` matches

4789

# zero or more URL path segments, which must be the last part of the URL path

4790

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4791

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4792

# The syntax `Variable` matches part of the URL path as specified by its

4793

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4794

# matches a single path segment, its template may be omitted, e.g. `{var}`

4795

# is equivalent to `{var=*}`.

4796

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4797

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

4798

# contains any reserved character, such characters should be percent-encoded

4799

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4800

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4801

# If a variable contains exactly one path segment, such as `"{var}"` or

4802

# `"{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]

4803

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

4804

# server side does the reverse decoding. Such variables show up in the

4805

# [Discovery

4806

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4807

# `{var}`.

4808

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4809

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

4810

# 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]

4811

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4812

# 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]

4813

# unchanged. Such variables show up in the

4814

# [Discovery

4815

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4816

# `{+var}`.

4817

#

4818

# ## Using gRPC API Service Configuration

4819

#

4820

# gRPC API Service Configuration (service config) is a configuration language

4821

# for configuring a gRPC service to become a user-facing product. The

4822

# service config is simply the YAML representation of the `google.api.Service`

4823

# proto message.

4824

#

4825

# As an alternative to annotating your proto file, you can configure gRPC

4826

# transcoding in your service config YAML files. You do this by specifying a

4827

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

4828

# effect as the proto annotation. This can be particularly useful if you

4829

# have a proto that is reused in multiple services. Note that any transcoding

4830

# specified in the service config will override any matching transcoding

4831

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

4838

# - selector: example.v1.Messaging.GetMessage

4839

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

4844

# proto to JSON conversion must follow the [proto3

4845

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

4846

#

4847

# While the single segment variable follows the semantics of

4848

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4849

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

4850

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

4851

# does not expand special characters like `?` and `#`, which would lead

4852

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

4853

# for multi segment variables.

4854

#

4855

# The path variables **must not** refer to any repeated or mapped field,

4856

# because client libraries are not capable of handling such variable expansion.

4857

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

4858

# The path variables **must not** capture the leading "/" character. The reason

4859

# 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]

4860

# character. For consistency, all path variables must share the same behavior.

4861

#

4862

# Repeated message fields must not be mapped to URL query parameters, because

4863

# no client library can support such complicated mapping.

4864

#

4865

# If an API needs to use a JSON array for request or response body, it can map

4866

# the request or response body to a repeated field. However, some gRPC

4867

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4868

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4869

"selector": "A String", # Selects a method to which this rule applies.

4870

#

4871

# Refer to selector for syntax details.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4872

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

4873

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

4874

# response body. When omitted, the entire response message will be used

4875

# as the HTTP response body.

4876

#

4877

# NOTE: The referred field must be present at the top-level of the response

4878

# message type.

4879

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

4880

# body, or `*` for mapping all request fields not captured by the path

4881

# pattern to the HTTP body, or omitted for not having any HTTP request body.

4882

#

4883

# NOTE: the referred field must be present at the top-level of the request

4884

# message type.

4885

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

4886

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4887

# not contain an `additional_bindings` field themselves (that is,

4888

# the nesting may only be one level deep).

4889

# Object with schema name: HttpRule

4890

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4891

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

4892

# included in the `pattern` field, such as HEAD, or "*" to leave the

4893

# HTTP method unspecified for this rule. The wild-card rule is useful

4894

# for services that provide content to Web (HTML) clients.

4895

"path": "A String", # The path matched by this custom verb.

4896

"kind": "A String", # The name of this custom HTTP verb.

4897

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4898

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

4899

# half-duplex streaming method.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4900

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4901

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

4902

# resources.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4903

},

4904

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4905

},

4906

"logs": [ # Defines the logs used by this service.

4907

{ # A description of a log type. Example in YAML format:

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4908

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4909

# - name: library.googleapis.com/activity_history

4910

# description: The history of borrowing and returning library items.

4911

# display_name: Activity

4912

# labels:

4913

# - key: /customer_id

4914

# description: Identifier of a library customer

4915

"description": "A String", # A human-readable description of this log. This information appears in

4916

# the documentation and can contain details.

4917

"labels": [ # The set of labels that are available to describe a specific log entry.

4918

# Runtime requests that contain labels not specified here are

4919

# considered invalid.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4920

{ # A description of a label.

4921

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4922

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4923

"key": "A String", # The label key.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4924

},

4925

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4926

"displayName": "A String", # The human-readable name for this log. This information appears on

4927

# the user interface and should be concise.

4928

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4929

# include the following characters: upper- and lower-case alphanumeric

4930

# characters [A-Za-z0-9], and punctuation characters including

4931

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

4932

},

4933

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

4934

"metrics": [ # Defines the metrics used by this service.

4935

{ # Defines a metric type and its schema. Once a metric descriptor is created,

4936

# deleting or altering it stops data collection and makes the metric type's

4937

# existing data unusable.

4938

#

4939

# The following are specific rules for service defined Monitoring metric

4940

# descriptors:

4941

#

4942

# * `type`, `metric_kind`, `value_type`, `description`, and `display_name`

4943

# fields are all required. The `unit` field must be specified

4944

# if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.

4945

# * Maximum of default 500 metric descriptors per service is allowed.

4946

# * Maximum of default 10 labels per metric descriptor is allowed.

4947

#

4948

# The default maximum limit can be overridden. Please follow

4949

# https://cloud.google.com/monitoring/quotas

4950

"unit": "A String", # The units in which the metric value is reported. It is only applicable

4951

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

4952

# defines the representation of the stored metric values.

4953

#

4954

# Different systems may scale the values to be more easily displayed (so a

4955

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

4956

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

4957

# `KBy`, then the value of the metric is always in thousands of bytes, no

4958

# matter how it may be displayed..

4959

#

4960

# If you want a custom metric to record the exact number of CPU-seconds used

4961

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

4962

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

4963

# CPU-seconds, then the value is written as `12005`.

4964

#

4965

# Alternatively, if you want a custom metric to record data in a more

4966

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

4967

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

4968

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

4969

#

4970

# The supported units are a subset of [The Unified Code for Units of

4971

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4972

#

4973

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

# * `1` dimensionless

4982

#

4983

# **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)

4992

# * `Y` yotta (10^24)

4993

#

4994

# * `m` milli (10^-3)

4995

# * `u` micro (10^-6)

4996

# * `n` nano (10^-9)

4997

# * `p` pico (10^-12)

4998

# * `f` femto (10^-15)

4999

# * `a` atto (10^-18)

5000

# * `z` zepto (10^-21)

5001

# * `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:

5012

#

5013

# * `/` division or ratio (as an infix operator). For examples,

5014

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

5015

# have `/s` in a metric `unit`; rates should always be computed at

5016

# query time from the underlying cumulative or delta value).

5017

# * `.` multiplication or composition (as an infix operator). For

5018

# examples, `GBy.d` or `k{watt}.h`.

5019

#

5020

# The grammar for a unit is as follows:

5021

#

5022

# Expression = Component { "." Component } { "/" Component } ;

5023

#

5024

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

5034

# is used alone, then the unit is equivalent to `1`. For examples,

5035

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

5036

# * `NAME` is a sequence of non-blank printable ASCII characters not

5037

# containing `{` or `}`.

5038

# * `1` represents a unitary [dimensionless

5039

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

5040

# as in `1/s`. It is typically used when none of the basic units are

5041

# appropriate. For example, "new users per day" can be represented as

5042

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

5043

# users). Alternatively, "thousands of page views per day" would be

5044

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

5045

# value of `5.3` would mean "5300 page views per day").

5046

# * `%` represents dimensionless value of 1/100, and annotates values giving

5047

# a percentage (so the metric values are typically in the range of 0..100,

5048

# and a metric value `3` means "3 percent").

5049

# * `10^2.%` indicates a metric contains a ratio, typically in the range

5050

# 0..1, that will be multiplied by 100 and displayed as a percentage

5051

# (so a metric value `0.03` means "3 percent").

5052

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5053

# Use sentence case without an ending period, for example "Request count".

5054

# This field is optional but it is recommended to be set for any metrics

5055

# associated with user-visible concepts, such as Quota.

5056

"monitoredResourceTypes": [ # Read-only. If present, then a time

5057

# series, which is identified partially by

5058

# a metric type and a MonitoredResourceDescriptor, that is associated

5059

# with this metric type can only be associated with one of the monitored

5060

# resource types listed here.

5061

"A String",

5062

],

5063

"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.

5064

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

5065

# periodically, consecutive data points are stored at this time interval,

5066

# excluding data loss due to errors. Metrics with a higher granularity have

5067

# a smaller sampling period.

5068

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

5069

# age are guaranteed to be ingested and available to be read, excluding

5070

# data loss due to errors.

5071

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5072

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5073

"name": "A String", # The resource name of the metric descriptor.

5074

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

5075

# Some combinations of `metric_kind` and `value_type` might not be supported.

5076

"launchStage": "A String", # Optional. The launch stage of the metric definition.

5077

"type": "A String", # The metric type, including its DNS name prefix. The type is not

5078

# URL-encoded.

5079

#

5080

# All service defined metrics must be prefixed with the service name, in the

5081

# format of `{service name}/{relative metric name}`, such as

5082

# `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric

5083

# name must follow:

5084

#

5085

# * Only upper and lower-case letters, digits, '/' and underscores '_' are

5086

# allowed.

5087

# * The maximum number of characters allowed for the relative_metric_name is

5088

# 100.

5089

#

5090

# All user-defined metric types have the DNS name

5091

# `custom.googleapis.com`, `external.googleapis.com`, or

5092

# `logging.googleapis.com/user/`.

5093

#

5094

# Metric types should use a natural hierarchical grouping. For example:

5095

#

5096

# "custom.googleapis.com/invoice/paid/amount"

5097

# "external.googleapis.com/prometheus/up"

5098

# "appengine.googleapis.com/http/server/response_latencies"

5099

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5100

"labels": [ # The set of labels that can be used to describe a specific

5101

# instance of this metric type.

5102

#

5103

# The label key name must follow:

5104

#

5105

# * Only upper and lower-case letters, digits and underscores (_) are

5106

# allowed.

5107

# * Label name must start with a letter or digit.

5108

# * The maximum length of a label name is 100 characters.

5109

#

5110

# For example, the

5111

# `appengine.googleapis.com/http/server/response_latencies` metric

5112

# type has a label for the HTTP response code, `response_code`, so

5113

# you can look at latencies for successful responses or just

5114

# for responses that failed.

5115

{ # A description of a label.

5116

"valueType": "A String", # The type of data that can be assigned to the label.

5117

"description": "A String", # A human-readable description for the label.

5118

"key": "A String", # The label key.

5119

},

5120

],

5121

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

5122

# Some combinations of `metric_kind` and `value_type` might not be supported.

5123

},

5124

],

5125

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5126

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5127

# Example:

5128

# <pre><code>documentation:

5129

# summary: >

5130

# The Google Calendar API gives access

5131

# to most calendar features.

5132

# pages:

5133

# - name: Overview

5134

# content: &#40;== include google/foo/overview.md ==&#41;

5135

# - name: Tutorial

5136

# content: &#40;== include google/foo/tutorial.md ==&#41;

5137

# subpages;

5138

# - name: Java

5139

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

5140

# rules:

5141

# - selector: google.calendar.Calendar.Get

5142

# description: >

5143

# ...

5144

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5149

# standard markdown features, definition lists, tables and fenced

5150

# code blocks are supported. Section headers can be provided and are

5151

# interpreted relative to the section nesting of the context where

5152

# a documentation fragment is embedded.

5153

#

5154

# Documentation from the IDL is merged with documentation defined

5155

# via the config at normalization time, where documentation provided

5156

# by config rules overrides IDL provided.

5157

#

5158

# A number of constructs specific to the API platform are supported

5159

# in documentation text.

5160

#

5161

# In order to reference a proto element, the following

5162

# notation can be used:

5163

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

5164

# To override the display text used for the link, this can be used:

5165

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

5166

# Text can be excluded from doc using the following notation:

5167

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

5168

#

5169

# A few directives are available in documentation. Note that

5170

# directives must appear on a single line to be properly

5171

# identified. The `include` directive includes a markdown file from

5172

# an external source:

5173

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

5174

# The `resource_for` directive marks a message to be the resource of

5175

# a collection in REST view. If it is not specified, tools attempt

5176

# to infer the resource from the operations in a collection:

5177

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

5178

# The directive `suppress_warning` does not directly affect documentation

5179

# and is documented together with service config validation.

5180

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

5181

# from the yaml file) is not suitable. This can be seen in any fully

5182

# specified service urls as well as sections that show a base that other

5183

# urls are relative to.

5184

"overview": "A String", # Declares a single overview page. For example:

5185

# <pre><code>documentation:

5186

# summary: ...

5187

# overview: &#40;== include overview.md ==&#41;

5188

# </code></pre>

5189

# This is a shortcut for the following declaration (using pages style):

5190

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

5195

# </code></pre>

5196

# Note: you cannot specify both `overview` field and `pages` field.

5197

"documentationRootUrl": "A String", # The URL to the root of documentation.

5198

"rules": [ # A list of documentation rules that apply to individual API elements.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5199

#

5200

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5201

{ # A documentation rule provides information about individual API elements.

5202

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

5203

# an element is marked as `deprecated`.

5204

"description": "A String", # Description of the selected API(s).

5205

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5206

# qualified name of the element which may end in "*", indicating a wildcard.

5207

# Wildcards are only allowed at the end and for a whole component of the

5208

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

5209

# wildcard will match one or more components. To specify a default for all

5210

# applicable elements, the whole pattern "*" is used.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5211

},

5212

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5213

"pages": [ # The top level pages for the documentation set.

5214

{ # Represents a documentation page. A page can contain subpages to represent

5215

# nested documentation set structure.

5216

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

5217

# ==&#41;</code> to include content from a Markdown file.

5218

"name": "A String", # The name of the page. It will be used as an identity of the page to

5219

# generate URI of the page, text of the link to this page in navigation,

5220

# etc. The full page name (start from the root page name to this page

5221

# concatenated with `.`) can be used as reference to the page in your

5222

# documentation. For example:

5223

# <pre><code>pages:

5224

# - name: Tutorial

5225

# content: &#40;== include tutorial.md ==&#41;

5226

# subpages:

5227

# - name: Java

5228

# content: &#40;== include tutorial_java.md ==&#41;

5229

# </code></pre>

5230

# You can reference `Java` page using Markdown reference link syntax:

5231

# `Java`.

5232

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5233

# honored in the generated docset.

5234

# Object with schema name: Page

],

},

],

"summary": "A String", # A short summary of what the service does. Can only be provided by

5239

# plain text.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5240

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5241

"configVersion": 42, # The semantic version of the service configuration. The config version

5242

# affects the interpretation of the service configuration. For example,

5243

# certain features are enabled by default for certain config versions.

5244

#

5245

# The latest config version is `3`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5246

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

5247

# usage.

5248

#

5249

# The metric based quota configuration works this way:

5250

# - The service configuration defines a set of metrics.

5251

# - For API calls, the quota.metric_rules maps methods to metrics with

5252

# corresponding costs.

5253

# - The quota.limits defines limits on the metrics, which will be used for

5254

# quota checks at runtime.

5255

#

5256

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

5262

# metric: library.googleapis.com/write_calls

5263

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

5269

# # except for the UpdateBook and DeleteBook methods. These two methods

5270

# # are mapped to the write_calls metric, with the UpdateBook method

5271

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

5276

# - selector: google.example.library.v1.LibraryService.UpdateBook

5277

# metric_costs:

5278

# library.googleapis.com/write_calls: 2

5279

# - selector: google.example.library.v1.LibraryService.DeleteBook

5280

# metric_costs:

5281

# library.googleapis.com/write_calls: 1

5282

#

5283

# Corresponding Metric definition:

5284

#

5285

# metrics:

5286

# - name: library.googleapis.com/read_calls

5287

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

5292

# display_name: Write requests

5293

# metric_kind: DELTA

5294

# value_type: INT64

5295

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5296

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

5297

# or more metrics.

5298

{ # Bind API methods to metrics. Binding a method to a metric causes that

5299

# metric's configured quota behaviors to apply to the method call.

5300

"selector": "A String", # Selects the methods to which this rule applies.

5301

#

5302

# Refer to selector for syntax details.

5303

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

5304

# cost applied to each metric.

5305

#

5306

# The key of the map is the metric name, and the values are the amount

5307

# increased for the metric against which the quota limits are defined.

5308

# The value must not be negative.

"a_key": "A String",

},

},

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5313

"limits": [ # List of `QuotaLimit` definitions for the service.

5314

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

5315

# for a limit type. There can be at most one limit for a duration and limit

5316

# type combination defined within a `QuotaGroup`.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5317

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

5318

# integer value that is the maximum number of requests allowed for the

5319

# specified unit. Currently only STANDARD is supported.

5320

"a_key": "A String",

5321

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5322

"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]

5323

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5324

# Used by group-based quotas only.

5325

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

5326

# The free tier is the number of tokens that will be subtracted from the

5327

# billed amount when billing is enabled.

5328

# This field can only be set on a limit with duration "1d", in a billable

5329

# group; it is invalid on any other limit. If this field is not set, it

5330

# 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]

5331

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5332

# Used by group-based quotas only.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5333

"displayName": "A String", # User-visible display name for this limit.

5334

# Optional. If not set, the UI will provide a default display name based on

5335

# the quota configuration. This field can be used to override the default

5336

# display name generated from the configuration.

5337

"description": "A String", # Optional. User-visible, extended description for this quota limit.

5338

# Should be used only when more context is needed to understand this limit

5339

# than provided by the limit's display name (see: `display_name`).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5340

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

5341

# duration. This is the number of tokens assigned when a client

5342

# application developer activates the service for his/her project.

5343

#

5344

# Specifying a value of 0 will block all requests. This can be used if you

5345

# are provisioning quota to selected consumers and blocking others.

5346

# Similarly, a value of -1 will indicate an unlimited quota. No other

5347

# negative values are allowed.

5348

#

5349

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5350

"name": "A String", # Name of the quota limit.

5351

#

5352

# The name must be provided, and it must be unique within the service. The

5353

# name can only include alphanumeric characters as well as '-'.

5354

#

5355

# The maximum length of the limit name is 64 characters.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5356

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

5357

# duration. Client application developers can override the default limit up

5358

# to this maximum. If specified, this value cannot be set to a value less

5359

# than the default limit. If not specified, it is set to the default limit.

5360

#

5361

# To allow clients to apply overrides with no upper bound, set this to -1,

5362

# indicating unlimited maximum quota.

5363

#

5364

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5365

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

5366

# the same metric will be checked together during runtime. The metric must be

5367

# defined within the service config.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5368

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

5369

# Metric.unit. The supported unit kinds are determined by the quota

5370

# backend system.

5371

#

5372

# Here are some examples:

5373

# * "1/min/{project}" for quota per minute per project.

5374

#

5375

# Note: the order of unit components is insignificant.

5376

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5377

},

5378

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5379

},

5380

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5381

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5389

# - google.foo.v1.AnotherError

5390

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

5391

"A String",

5392

],

5393

"rules": [ # The list of custom error rules that apply to individual API messages.

5394

#

5395

# **NOTE:** All service configuration rules follow "last one wins" order.

5396

{ # A custom error rule.

5397

"selector": "A String", # Selects messages to which this rule applies.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5398

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5399

# Refer to selector for syntax details.

5400

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5401

# objects of this type will be filtered when they appear in error payload.

},

],

},

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

5406

#

5407

# Example for an API targeted for external use:

5408

#

5409

# name: calendar.googleapis.com

5410

# authentication:

5411

# providers:

5412

# - id: google_calendar_auth

5413

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5414

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

5419

"rules": [ # A list of authentication rules that apply to individual API methods.

5420

#

5421

# **NOTE:** All service configuration rules follow "last one wins" order.

5422

{ # Authentication rules for the service.

5423

#

5424

# By default, if a method has any authentication requirements, every request

5425

# must include a valid credential matching one of the requirements.

5426

# It's an error to include more than one kind of credential in a single

5427

# request.

5428

#

5429

# If a method doesn't have any auth requirements, request credentials will be

5430

# ignored.

5431

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

5432

# there are scopes defined for "Read-only access to Google Calendar" and

5433

# "Access to Cloud Platform". Users can consent to a scope for an application,

5434

# giving it permission to access that data on their behalf.

5435

#

5436

# OAuth scope specifications should be fairly coarse grained; a user will need

5437

# to see and understand the text description of what your scope means.

5438

#

5439

# In most cases: use one or at most two OAuth scopes for an entire family of

5440

# products. If your product has multiple APIs, you should probably be sharing

5441

# the OAuth scope across all of those APIs.

5442

#

5443

# When you need finer grained OAuth consent screens: talk with your product

5444

# management about how developers will use them in practice.

5445

#

5446

# Please note that even though each of the canonical scopes is enough for a

5447

# request to be accepted and passed to the backend, a request can still fail

5448

# due to the backend requiring additional scopes or permissions.

5449

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

5450

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

5455

# https://www.googleapis.com/auth/calendar.read

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5456

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5457

"requirements": [ # Requirements for additional authentication providers.

5458

{ # User-defined authentication requirements, including support for

5459

# [JSON Web Token

5460

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5461

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

5466

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

5467

# implemented and accepted in all the runtime components.

5468

#

5469

# The list of JWT

5470

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5471

# that are allowed to access. A JWT containing any of these audiences will

5472

# be accepted. When this setting is absent, only JWTs with audience

5473

# "https://Service_name/API_name"

5474

# will be accepted. For example, if no audiences are in the setting,

5475

# LibraryService API will only accept JWTs with the following audience

5476

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5481

# bookstore_web.apps.googleusercontent.com

5482

},

5483

],

5484

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5485

"selector": "A String", # Selects the methods to which this rule applies.

5486

#

5487

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5488

},

5489

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5490

"providers": [ # Defines a set of authentication providers that a service supports.

5491

{ # Configuration for an authentication provider, including support for

5492

# [JSON Web Token

5493

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5494

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

5495

# `AuthRequirement.provider_id`.

5496

#

5497

# Example: "bookstore_auth".

5498

"issuer": "A String", # Identifies the principal that issued the JWT. See

5499

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

5500

# Usually a URL or an email address.

5501

#

5502

# Example: https://securetoken.google.com

5503

# Example: 1234567-compute@developer.gserviceaccount.com

5504

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

5505

# [OpenID

5506

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

5507

# Optional if the key set document:

5508

# - can be retrieved from

5509

# [OpenID

5510

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

5511

# the issuer.

5512

# - can be inferred from the email domain of the issuer (e.g. a Google

5513

# service account).

5514

#

5515

# Example: https://www.googleapis.com/oauth2/v1/certs

5516

"audiences": "A String", # The list of JWT

5517

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5518

# that are allowed to access. A JWT containing any of these audiences will

5519

# be accepted. When this setting is absent, JWTs with audiences:

5520

# - "https://[service.name]/[google.protobuf.Api.name]"

5521

# - "https://[service.name]/"

5522

# will be accepted.

5523

# For example, if no audiences are in the setting, LibraryService API will

5524

# accept JWTs with the following audiences:

5525

# -

5526

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

5527

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5532

# bookstore_web.apps.googleusercontent.com

5533

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

5534

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

5535

"jwtLocations": [ # Defines the locations to extract the JWT.

5536

#

5537

# JWT locations can be either from HTTP headers or URL query parameters.

5538

# The rule is that the first match wins. The checking order is: checking

5539

# all headers first, then URL query parameters.

5540

#

5541

# If not specified, default to use following 3 locations:

5542

# 1) Authorization: Bearer

5543

# 2) x-goog-iap-jwt-assertion

5544

# 3) access_token query parameter

5545

#

5546

# Default locations can be specified as followings:

5547

# jwt_locations:

5548

# - header: Authorization

5549

# value_prefix: "Bearer "

5550

# - header: x-goog-iap-jwt-assertion

5551

# - query: access_token

5552

{ # Specifies a location to extract JWT from an API request.

5553

"query": "A String", # Specifies URL query parameter name to extract JWT token.

5554

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

5555

# Only applies to "in" header type. Must be empty for "in" query type.

5556

# If not empty, the header value has to match (case sensitive) this prefix.

5557

# If not matched, JWT will not be extracted. If matched, JWT will be

5558

# extracted after the prefix is removed.

5559

#

5560

# For example, for "Authorization: Bearer {JWT}",

5561

# value_prefix="Bearer " with a space at the end.

5562

"header": "A String", # Specifies HTTP header name to extract JWT token.

},

],

},

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5567

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5568

"title": "A String", # The product title for this service.

5569

"producerProjectId": "A String", # The Google project that owns this service.

5570

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

5571

# of the google.protobuf.Api needs to be provided by the configuration

5572

# author, as the remaining fields will be derived from the IDL during the

5573

# normalization process. It is an error to specify an API interface here

5574

# which cannot be resolved against the associated IDL files.

5575

{ # Api is a light-weight descriptor for an API Interface.

5576

#

5577

# Interfaces are also described as "protocol buffer services" in some contexts,

5578

# such as by the "service" keyword in a .proto file, but they are different

5579

# from API Services, which represent a concrete implementation of an interface

5580

# as opposed to simply a description of methods and bindings. They are also

5581

# sometimes simply referred to as "APIs" in other contexts, such as the name of

5582

# this message itself. See https://cloud.google.com/apis/design/glossary for

5583

# detailed terminology.

5584

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

5585

# message.

5586

# protobuf element, like the file in which it is defined.

5587

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5588

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5589

},

5590

"syntax": "A String", # The source syntax of the service.

5591

"methods": [ # The methods of this interface, in unspecified order.

5592

{ # Method represents a method of an API interface.

5593

"options": [ # Any metadata attached to the method.

5594

{ # A protocol buffer option, which can be attached to a message, field,

5595

# enumeration, etc.

5596

"value": { # The option's value packed in an Any message. If the value is a primitive,

5597

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5598

# should be used. If the value is an enum, it should be stored as an int32

5599

# value using the google.protobuf.Int32Value type.

5600

"a_key": "", # Properties of the object. Contains field @type with type URL.

5601

},

5602

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5603

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5604

# For custom options, it should be the fully-qualified name. For example,

5605

# `"google.api.http"`.

5606

},

5607

],

5608

"responseStreaming": True or False, # If true, the response is streamed.

5609

"syntax": "A String", # The source syntax of this method.

5610

"requestTypeUrl": "A String", # A URL of the input message type.

5611

"name": "A String", # The simple name of this method.

5612

"responseTypeUrl": "A String", # The URL of the output message type.

5613

"requestStreaming": True or False, # If true, the request is streamed.

5614

},

5615

],

5616

"name": "A String", # The fully qualified name of this interface, including package name

5617

# followed by the interface's simple name.

5618

"version": "A String", # A version string for this interface. If specified, must have the form

5619

# `major-version.minor-version`, as in `1.10`. If the minor version is

5620

# omitted, it defaults to zero. If the entire version field is empty, the

5621

# major version is derived from the package name, as outlined below. If the

5622

# field is not empty, the version in the package name will be verified to be

5623

# consistent with what is provided here.

5624

#

5625

# The versioning schema uses [semantic

5626

# versioning](http://semver.org) where the major version number

5627

# indicates a breaking change and the minor version an additive,

5628

# non-breaking change. Both version numbers are signals to users

5629

# what to expect from different versions, and should be carefully

5630

# chosen based on the product plan.

5631

#

5632

# The major version is also reflected in the package name of the

5633

# interface, which must end in `v<major-version>`, as in

5634

# `google.feature.v1`. For major versions 0 and 1, the suffix can

5635

# be omitted. Zero major versions must only be used for

5636

# experimental, non-GA interfaces.

5637

"options": [ # Any metadata attached to the interface.

5638

{ # A protocol buffer option, which can be attached to a message, field,

5639

# enumeration, etc.

5640

"value": { # The option's value packed in an Any message. If the value is a primitive,

5641

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5642

# should be used. If the value is an enum, it should be stored as an int32

5643

# value using the google.protobuf.Int32Value type.

5644

"a_key": "", # Properties of the object. Contains field @type with type URL.

5645

},

5646

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5647

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5648

# For custom options, it should be the fully-qualified name. For example,

5649

# `"google.api.http"`.

5650

},

5651

],

5652

"mixins": [ # Included interfaces. See Mixin.

5653

{ # Declares an API Interface to be included in this interface. The including

5654

# interface must redeclare all the methods from the included interface, but

5655

# documentation and options are inherited as follows:

5656

#

5657

# - If after comment and whitespace stripping, the documentation

5658

# string of the redeclared method is empty, it will be inherited

5659

# from the original method.

5660

#

5661

# - Each annotation belonging to the service config (http,

5662

# visibility) which is not set in the redeclared method will be

5663

# inherited.

5664

#

5665

# - If an http annotation is inherited, the path pattern will be

5666

# modified as follows. Any version prefix will be replaced by the

5667

# version of the including interface plus the root path if

5668

# specified.

5669

#

5670

# Example of a simple mixin:

5671

#

5672

# package google.acl.v1;

5673

# service AccessControl {

5674

# // Get the underlying ACL object.

5675

# rpc GetAcl(GetAclRequest) returns (Acl) {

5676

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

5681

# service Storage {

5682

# // rpc GetAcl(GetAclRequest) returns (Acl);

5683

#

5684

# // Get a data record.

5685

# rpc GetData(GetDataRequest) returns (Data) {

5686

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

5691

#

5692

# apis:

5693

# - name: google.storage.v2.Storage

5694

# mixins:

5695

# - name: google.acl.v1.AccessControl

5696

#

5697

# The mixin construct implies that all methods in `AccessControl` are

5698

# also declared with same name and request/response types in

5699

# `Storage`. A documentation generator or annotation processor will

5700

# see the effective `Storage.GetAcl` method after inherting

5701

# documentation and annotations as follows:

5702

#

5703

# service Storage {

5704

# // Get the underlying ACL object.

5705

# rpc GetAcl(GetAclRequest) returns (Acl) {

5706

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

5712

#

5713

# If the `root` field in the mixin is specified, it should be a

5714

# relative path under which inherited HTTP paths are placed. Example:

5715

#

5716

# apis:

5717

# - name: google.storage.v2.Storage

5718

# mixins:

5719

# - name: google.acl.v1.AccessControl

5720

# root: acls

5721

#

5722

# This implies the following inherited HTTP annotation:

5723

#

5724

# service Storage {

5725

# // Get the underlying ACL object.

5726

# rpc GetAcl(GetAclRequest) returns (Acl) {

5727

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

5732

# are rooted.

5733

"name": "A String", # The fully qualified name of the interface which is included.

},

],

},

],

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5739

# by the client for tracking purpose. Must be no longer than 63 characters

5740

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

5741

# empty, the server may choose to generate one instead.

5742

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5743

# with the same name as the service is automatically generated to service all

5744

# defined APIs.

5745

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5746

# A service may expose any number of endpoints, and all endpoints share the

5747

# same service configuration, such as quota configuration and monitoring

5748

# configuration.

5749

#

5750

# Example service configuration:

5751

#

5752

# name: library-example.googleapis.com

5753

# endpoints:

5754

# # Below entry makes 'google.example.library.v1.Library'

5755

# # API be served from endpoint address library-example.googleapis.com.

5756

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5757

# # it to decide whether the subsequent cross-origin request is

5758

# # allowed to proceed.

5759

# - name: library-example.googleapis.com

5760

# allow_cors: true

5761

"name": "A String", # The canonical name of this endpoint.

5762

"allowCors": True or False, # Allowing

5763

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5764

# cross-domain traffic, would allow the backends served from this endpoint to

5765

# receive and respond to HTTP OPTIONS requests. The response will be used by

5766

# the browser to determine whether the subsequent cross-origin request is

5767

# allowed to proceed.

5768

"target": "A String", # The specification of an Internet routable address of API frontend that will

5769

# handle requests to this [API

5770

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

5771

# either a valid IPv4 address or a fully-qualified domain name. For example,

5772

# "8.8.8.8" or "myservice.appspot.com".

5773

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

5774

# please specify multiple google.api.Endpoint for each of the intended

5775

# aliases.

5776

#

5777

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"systemParameters": { # ### System parameter configuration # System parameter configuration.

5783

#

5784

# A system parameter is a special kind of parameter defined by the API

5785

# system, not by an individual API. It is typically mapped to an HTTP header

5786

# and/or a URL query parameter. This configuration specifies which methods

5787

# change the names of the system parameters.

5788

"rules": [ # Define system parameters.

5789

#

5790

# The parameters defined here will override the default parameters

5791

# implemented by the system. If this field is missing from the service

5792

# config, default system parameters will be used. Default system parameters

5793

# and names is implementation-dependent.

5794

#

5795

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

5803

#

5804

#

5805

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

5810

# parameters:

5811

# - name: api_key

5812

# http_header: Api-Key1

5813

# - name: api_key

5814

# http_header: Api-Key2

5815

#

5816

# **NOTE:** All service configuration rules follow "last one wins" order.

5817

{ # Define a system parameter rule mapping system parameter definitions to

5818

# methods.

5819

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

5820

# For a given method call, only one of them should be used. If multiple

5821

# names are used the behavior is implementation-dependent.

5822

# If none of the specified names are present the behavior is

5823

# parameter-dependent.

5824

{ # Define a parameter's name and location. The parameter may be passed as either

5825

# an HTTP header or a URL query parameter, and if both are passed the behavior

5826

# is implementation-dependent.

5827

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

5828

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

5829

# insensitive.

5830

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

# sensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5835

# methods in all APIs.

5836

#

5837

# Refer to selector for syntax details.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5842

# by the Service.monitoring and Service.logging configurations.

5843

{ # An object that describes the schema of a MonitoredResource object using a

5844

# type name and a set of labels. For example, the monitored resource

5845

# descriptor for Google Compute Engine VM instances has a type of

5846

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5847

# `"zone"` to identify particular VM instances.

5848

#

5849

# Different services can support different monitored resource types.

5850

#

5851

# The following are specific rules to service defined monitored resources for

5852

# Monitoring and Logging:

5853

#

5854

# * The `type`, `display_name`, `description`, `labels` and `launch_stage`

5855

# fields are all required.

5856

# * The first label of the monitored resource descriptor must be

5857

# `resource_container`. There are legacy monitored resource descritptors

5858

# start with `project_id`.

5859

# * It must include a `location` label.

5860

# * Maximum of default 5 service defined monitored resource descriptors

5861

# is allowed per service.

5862

# * Maximum of default 10 labels per monitored resource is allowed.

5863

#

5864

# The default maximum limit can be overridden. Please follow

5865

# https://cloud.google.com/monitoring/quotas

5866

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5867

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5868

# {type} is the value of the `type` field in this object and

5869

# {project_id} is a project ID that provides API-specific context for

5870

# accessing the type. APIs that do not use project information can use the

5871

# resource name format `"monitoredResourceDescriptors/{type}"`.

5872

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

5873

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5874

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5875

# without any article or other determiners. For example,

5876

# `"Google Cloud SQL Database"`.

5877

"labels": [ # Required. A set of labels used to describe instances of this monitored

5878

# resource type.

5879

# The label key name must follow:

5880

#

5881

# * Only upper and lower-case letters, digits and underscores (_) are

5882

# allowed.

5883

# * Label name must start with a letter or digit.

5884

# * The maximum length of a label name is 100 characters.

5885

#

5886

# For example, an individual Google Cloud SQL database is

5887

# identified by values for the labels `database_id` and `location`.

5888

{ # A description of a label.

5889

"valueType": "A String", # The type of data that can be assigned to the label.

5890

"description": "A String", # A human-readable description for the label.

5891

"key": "A String", # The label key.

5892

},

5893

],

5894

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5895

# be used in documentation.

5896

"type": "A String", # Required. The monitored resource type. For example, the type

5897

# `cloudsql_database` represents databases in Google Cloud SQL.

5898

#

5899

# All service defined monitored resource types must be prefixed with the

5900

# service name, in the format of `{service name}/{relative resource name}`.

5901

# The relative resource name must follow:

5902

#

5903

# * Only upper and lower-case letters and digits are allowed.

5904

# * It must start with upper case character and is recommended to use Upper

5905

# Camel Case style.

5906

# * The maximum number of characters allowed for the relative_resource_name

5907

# is 100.

5908

#

5909

# Note there are legacy service monitored resources not following this rule.

5910

},

5911

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5912

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5913

#

5914

# Example:

5915

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

5921

# - google.rpc.context.OriginContext

5922

#

5923

# The above specifies that all methods in the API request

5924

# `google.rpc.context.ProjectContext` and

5925

# `google.rpc.context.OriginContext`.

5926

#

5927

# Available context types are defined in package

5928

# `google.rpc.context`.

5929

#

5930

# This also provides mechanism to whitelist any protobuf message extension that

5931

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

5932

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

5933

# 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"

5941

# allowed_request_extensions:

5942

# - google.foo.v1.NewExtension

5943

# allowed_response_extensions:

5944

# - google.foo.v1.NewExtension

5945

#

5946

# You can also specify extension ID instead of fully qualified extension name

5947

# here.

5948

"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]

5949

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5950

# **NOTE:** All service configuration rules follow "last one wins" order.

5951

{ # A context rule provides information about the context for an individual API

5952

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5953

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5954

#

5955

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

5956

"requested": [ # A list of full type names of requested contexts.

5957

"A String",

5958

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5959

"provided": [ # A list of full type names of provided contexts.

5960

"A String",

5961

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5962

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5963

# side channel from client to backend.

5964

"A String",

5965

],

5966

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5967

# side channel from backend to client.

5968

"A String",

5969

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

],

},

}</pre>

</div>

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5977

<code class="details" id="list">list(serviceName, pageSize=None, pageToken=None, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5978

<pre>Lists the history of the service configuration for a managed service,

5979

from the newest to the oldest.

5980

5981

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

5982

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]

5983

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5984

pageSize: integer, The max number of items to include in the response list. Page size is 50

5985

if not specified. Maximum value is 100.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

5986

pageToken: string, The token of the page to retrieve.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5987

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5994

5995

{ # Response message for ListServiceConfigs method.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

5996

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5997

{ # `Service` is the root object of Google service configuration schema. It

5998

# describes basic information about a service, such as the name and the

5999

# title, and delegates other aspects to sub-sections. Each sub-section is

6000

# either a proto message or a repeated proto message that configures a

6001

# 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]

6006

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6007

# name: calendar.googleapis.com

6008

# title: Google Calendar API

6009

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6010

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6011

# authentication:

6012

# providers:

6013

# - id: google_calendar_auth

6014

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

6015

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6016

# rules:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6017

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6018

# requirements:

6019

# provider_id: google_calendar_auth

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6020

"enums": [ # A list of all enum types included in this API service. Enums

6021

# referenced directly or indirectly by the `apis` are automatically

6022

# included. Enums which are not referenced but shall be included

6023

# should be listed here by name. Example:

6024

#

6025

# enums:

6026

# - name: google.someapi.v1.SomeEnum

6027

{ # Enum type definition.

6028

"options": [ # Protocol buffer options.

6029

{ # A protocol buffer option, which can be attached to a message, field,

6030

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6031

"value": { # The option's value packed in an Any message. If the value is a primitive,

6032

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6033

# should be used. If the value is an enum, it should be stored as an int32

6034

# value using the google.protobuf.Int32Value type.

6035

"a_key": "", # Properties of the object. Contains field @type with type URL.

6036

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6037

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6038

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6039

# For custom options, it should be the fully-qualified name. For example,

6040

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6041

},

6042

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6043

"enumvalue": [ # Enum value definitions.

6044

{ # Enum value definition.

6045

"name": "A String", # Enum value name.

6046

"options": [ # Protocol buffer options.

6047

{ # A protocol buffer option, which can be attached to a message, field,

6048

# enumeration, etc.

6049

"value": { # The option's value packed in an Any message. If the value is a primitive,

6050

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6051

# should be used. If the value is an enum, it should be stored as an int32

6052

# value using the google.protobuf.Int32Value type.

6053

"a_key": "", # Properties of the object. Contains field @type with type URL.

6054

},

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

},

6060

],

6061

"number": 42, # Enum value number.

6062

},

6063

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6064

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6065

# protobuf element, like the file in which it is defined.

6066

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6067

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6068

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6069

"name": "A String", # Enum type name.

6070

"syntax": "A String", # The source syntax.

6071

},

6072

],

6073

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

6074

"rules": [ # A list of API backend rules that apply to individual API methods.

6075

#

6076

# **NOTE:** All service configuration rules follow "last one wins" order.

6077

{ # A backend rule provides configuration for an individual API element.

6078

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

6079

# original "Authorization" HTTP header will be preserved. If the header is

6080

# used to carry the original token and is expected by the backend, this

6081

# field must be set to true to preserve the header.

6082

"address": "A String", # The address of the API backend.

6083

#

6084

# The scheme is used to determine the backend protocol and security.

6085

# The following schemes are accepted:

6086

#

6087

# 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

6094

# may cause constrasting behaviors across platforms.

6095

#

6096

# If the port is unspecified, the default is:

6097

# - 80 for schemes without TLS

6098

# - 443 for schemes with TLS

6099

#

6100

# For HTTP backends, use protocol

6101

# to specify the protocol version.

6102

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

6103

# value lower than this will be rejected.

6104

"selector": "A String", # Selects the methods to which this rule applies.

6105

#

6106

# Refer to selector for syntax details.

6107

"protocol": "A String", # The protocol used for sending a request to the backend.

6108

# The supported values are "http/1.1" and "h2".

6109

#

6110

# The default value is inferred from the scheme in the

# address field:

#

# SCHEME PROTOCOL

# http:// http/1.1

# https:// http/1.1

# grpc:// h2

# grpcs:// h2

#

# For secure HTTP backends (https://) that support HTTP/2, set this field

6120

# to "h2" for improved performance.

6121

#

6122

# Configuring this field to non-default values is only supported for secure

6123

# HTTP backends. This field will be ignored for all other backends.

6124

#

6125

# See

6126

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

6127

# for more details on the supported values.

6128

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

6129

# operation. The default is no deadline.

6130

"pathTranslation": "A String",

6131

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

6132

# This ID token will be added in the HTTP "authorization" header, and sent

6133

# to the backend.

6134

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

6135

# varies based on the request protocol and deployment environment.

},

],

},

"systemTypes": [ # A list of all proto message types included in this API service.

6140

# It serves similar purpose as [google.api.Service.types], except that

6141

# these types are not needed by user-defined APIs. Therefore, they will not

6142

# show up in the generated discovery doc. This field should only be used

6143

# to define system APIs in ESF.

6144

{ # A protocol buffer message type.

6145

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6146

# protobuf element, like the file in which it is defined.

6147

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6148

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6149

},

6150

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6151

"A String",

6152

],

6153

"fields": [ # The list of fields.

6154

{ # A single field of a message type.

6155

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6156

# types. The first type has index 1; zero means the type is not in the list.

6157

"name": "A String", # The field name.

6158

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6159

"packed": True or False, # Whether to use alternative packed wire representation.

6160

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6161

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6162

"cardinality": "A String", # The field cardinality.

6163

"jsonName": "A String", # The field JSON name.

6164

"kind": "A String", # The field type.

6165

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6166

{ # A protocol buffer option, which can be attached to a message, field,

6167

# enumeration, etc.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6168

"value": { # The option's value packed in an Any message. If the value is a primitive,

6169

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6170

# should be used. If the value is an enum, it should be stored as an int32

6171

# value using the google.protobuf.Int32Value type.

6172

"a_key": "", # Properties of the object. Contains field @type with type URL.

6173

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6174

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6175

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6176

# For custom options, it should be the fully-qualified name. For example,

6177

# `"google.api.http"`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6178

},

6179

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6180

"number": 42, # The field number.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6181

},

6182

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6183

"options": [ # The protocol buffer options.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6184

{ # A protocol buffer option, which can be attached to a message, field,

6185

# enumeration, etc.

6186

"value": { # The option's value packed in an Any message. If the value is a primitive,

6187

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6188

# should be used. If the value is an enum, it should be stored as an int32

6189

# value using the google.protobuf.Int32Value type.

6190

"a_key": "", # Properties of the object. Contains field @type with type URL.

6191

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6192

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6193

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6194

# For custom options, it should be the fully-qualified name. For example,

6195

# `"google.api.http"`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6196

},

6197

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6198

"syntax": "A String", # The source syntax.

6199

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6200

},

6201

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6202

"name": "A String", # The service name, which is a DNS-like logical identifier for the

6203

# service, such as `calendar.googleapis.com`. The service name

6204

# typically goes through DNS verification to make sure the owner

6205

# of the service also owns the DNS name.

6206

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

6207

"sourceFiles": [ # All files used during config generation.

6208

{

6209

"a_key": "", # Properties of the object. Contains field @type with type URL.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6210

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6211

],

6212

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6213

"billing": { # Billing related configuration of the service. # Billing configuration.

6214

#

6215

# The following example shows how to configure monitored resources and metrics

6216

# for billing, `consumer_destinations` is the only supported destination and

6217

# the monitored resources need at least one label key

6218

# `cloud.googleapis.com/location` to indicate the location of the billing

6219

# usage, using different monitored resources between monitoring and billing is

6220

# recommended so they can be evolved independently:

6221

#

6222

#

6223

# monitored_resources:

6224

# - type: library.googleapis.com/billing_branch

6225

# labels:

6226

# - key: cloud.googleapis.com/location

6227

# description: |

6228

# Predefined label to support billing location restriction.

6229

# - key: city

6230

# description: |

6231

# Custom label to define the city where the library branch is located

6232

# in.

6233

# - key: name

6234

# description: Custom label to define the name of the library branch.

6235

# metrics:

6236

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# billing:

# consumer_destinations:

6242

# - monitored_resource: library.googleapis.com/billing_branch

6243

# metrics:

6244

# - library.googleapis.com/book/borrowed_count

6245

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

6246

# There can be multiple consumer destinations per service, each one must have

6247

# a different monitored resource type. A metric can be used in at most

6248

# one consumer destination.

6249

{ # Configuration of a specific billing destination (Currently only support

6250

# bill against consumer project).

6251

"metrics": [ # Names of the metrics to report to this billing destination.

6252

# Each name must be defined in Service.metrics section.

6253

"A String",

6254

],

6255

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6256

# Service.monitored_resources section.

},

],

},

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

6261

#

6262

# The example below shows how to configure monitored resources and metrics

6263

# for monitoring. In the example, a monitored resource and two metrics are

6264

# defined. The `library.googleapis.com/book/returned_count` metric is sent

6265

# to both producer and consumer projects, whereas the

6266

# `library.googleapis.com/book/num_overdue` metric is only sent to the

6267

# consumer project.

6268

#

6269

# monitored_resources:

6270

# - type: library.googleapis.com/Branch

6271

# display_name: "Library Branch"

6272

# description: "A branch of a library."

6273

# launch_stage: GA

6274

# labels:

6275

# - key: resource_container

6276

# description: "The Cloud container (ie. project id) for the Branch."

6277

# - key: location

6278

# description: "The location of the library branch."

6279

# - key: branch_id

6280

# description: "The id of the branch."

6281

# metrics:

6282

# - name: library.googleapis.com/book/returned_count

6283

# display_name: "Books Returned"

6284

# description: "The count of books that have been returned."

# launch_stage: GA

# metric_kind: DELTA

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

6292

# - name: library.googleapis.com/book/num_overdue

6293

# display_name: "Books Overdue"

6294

# description: "The current number of overdue books."

# launch_stage: GA

# metric_kind: GAUGE

# value_type: INT64

# unit: "1"

# labels:

# - key: customer_id

# description: "The id of the customer."

6302

# monitoring:

6303

# producer_destinations:

6304

# - monitored_resource: library.googleapis.com/Branch

6305

# metrics:

6306

# - library.googleapis.com/book/returned_count

6307

# consumer_destinations:

6308

# - monitored_resource: library.googleapis.com/Branch

6309

# metrics:

6310

# - library.googleapis.com/book/returned_count

6311

# - library.googleapis.com/book/num_overdue

6312

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

6313

# There can be multiple producer destinations. A monitored resource type may

6314

# appear in multiple monitoring destinations if different aggregations are

6315

# needed for different sets of metrics associated with that monitored

6316

# resource type. A monitored resource and metric pair may only be used once

6317

# in the Monitoring configuration.

6318

{ # Configuration of a specific monitoring destination (the producer project

6319

# or the consumer project).

6320

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6321

# Service.monitored_resources section.

6322

"metrics": [ # Types of the metrics to report to this monitoring destination.

6323

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

6329

# There can be multiple consumer destinations. A monitored resource type may

6330

# appear in multiple monitoring destinations if different aggregations are

6331

# needed for different sets of metrics associated with that monitored

6332

# resource type. A monitored resource and metric pair may only be used once

6333

# in the Monitoring configuration.

6334

{ # Configuration of a specific monitoring destination (the producer project

6335

# or the consumer project).

6336

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6337

# Service.monitored_resources section.

6338

"metrics": [ # Types of the metrics to report to this monitoring destination.

6339

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"logging": { # Logging configuration of the service. # Logging configuration.

6346

#

6347

# The following example shows how to configure logs to be sent to the

6348

# producer and consumer projects. In the example, the `activity_history`

6349

# log is sent to both the producer and consumer projects, whereas the

6350

# `purchase_history` log is only sent to the producer project.

6351

#

6352

# monitored_resources:

6353

# - type: library.googleapis.com/branch

6354

# labels:

6355

# - key: /city

6356

# description: The city where the library branch is located in.

6357

# - key: /name

6358

# description: The name of the branch.

6359

# logs:

6360

# - name: activity_history

6361

# labels:

6362

# - key: /customer_id

6363

# - name: purchase_history

6364

# logging:

6365

# producer_destinations:

6366

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

6371

# - monitored_resource: library.googleapis.com/branch

6372

# logs:

6373

# - activity_history

6374

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

6375

# There can be multiple producer destinations, each one must have a

6376

# different monitored resource type. A log can be used in at most

6377

# one producer destination.

6378

{ # Configuration of a specific logging destination (the producer project

6379

# or the consumer project).

6380

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

6381

# Service.monitored_resources section.

6382

"logs": [ # Names of the logs to be sent to this destination. Each name must

6383

# be defined in the Service.logs section. If the log name is

6384

# not a domain scoped name, it will be automatically prefixed with

6385

# the service name followed by "/".

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

6391

# There can be multiple consumer destinations, each one must have a

6392

# different monitored resource type. A log can be used in at most

6393

# one consumer destination.

6394

{ # Configuration of a specific logging destination (the producer project

6395

# or the consumer project).

6396

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

6397

# Service.monitored_resources section.

6398

"logs": [ # Names of the logs to be sent to this destination. Each name must

6399

# be defined in the Service.logs section. If the log name is

6400

# not a domain scoped name, it will be automatically prefixed with

6401

# the service name followed by "/".

"A String",

],

},

],

},

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

6408

# service controller handles features like abuse, quota, billing, logging,

6409

# monitoring, etc.

6410

"environment": "A String", # The service control environment to use. If empty, no control plane

6411

# feature (like quota and billing) will be enabled.

6412

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6413

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

6414

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

6415

# service. Each requirement is of the form <service.name>/<requirement-id>;

6416

# for example 'serviceusage.googleapis.com/billing-enabled'.

6417

"A String",

6418

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6419

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

6420

#

6421

#

6422

# Use this field to configure per-product per-project service identity.

6423

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

6428

# display_name: "Cloud XXX Service Agent"

6429

# description: "Used as the identity of Cloud XXX to access resources"

6430

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

6431

#

6432

# An example name would be:

6433

# `projects/123456789`

6434

"description": "A String", # Optional. A user-specified opaque description of the service account.

6435

# Must be less than or equal to 256 UTF-8 bytes.

6436

"displayName": "A String", # Optional. A user-specified name for the service account.

6437

# Must be less than or equal to 100 UTF-8 bytes.

6438

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6439

"rules": [ # A list of usage rules that apply to individual API methods.

6440

#

6441

# **NOTE:** All service configuration rules follow "last one wins" order.

6442

{ # Usage configuration rules for the service.

6443

#

6444

# NOTE: Under development.

6445

#

6446

#

6447

# Use this rule to configure unregistered calls for the service. Unregistered

6448

# calls are calls that do not contain consumer project identity.

6449

# (Example: calls that do not contain an API key).

6450

# By default, API methods do not allow unregistered calls, and each method call

6451

# must be identified by a consumer project identity. Use this rule to

6452

# allow/disallow unregistered calls.

6453

#

6454

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

6460

#

6461

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

6466

# allow_unregistered_calls: true

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6467

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

6468

# plane features, such as quota and billing, will not be available.

6469

# This flag is used by Google Cloud Endpoints to bypass checks for internal

6470

# methods, such as service health check methods.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6471

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

6472

# methods in all APIs.

6473

#

6474

# Refer to selector for syntax details.

6475

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

6476

# that don't identify any user or application.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6477

},

6478

],

6479

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

6480

# service producer.

6481

#

6482

# Google Service Management currently only supports

6483

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

6484

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

6485

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

6486

# documented in https://cloud.google.com/pubsub/docs/overview.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6487

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6488

"types": [ # A list of all proto message types included in this API service.

6489

# Types referenced directly or indirectly by the `apis` are

6490

# automatically included. Messages which are not referenced but

6491

# shall be included, such as types used by the `google.protobuf.Any` type,

6492

# should be listed here by name. Example:

6493

#

6494

# types:

6495

# - name: google.protobuf.Int32

6496

{ # A protocol buffer message type.

6497

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6498

# protobuf element, like the file in which it is defined.

6499

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6500

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6501

},

6502

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6503

"A String",

6504

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6505

"fields": [ # The list of fields.

6506

{ # A single field of a message type.

6507

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6508

# types. The first type has index 1; zero means the type is not in the list.

6509

"name": "A String", # The field name.

6510

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6511

"packed": True or False, # Whether to use alternative packed wire representation.

6512

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6513

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6514

"cardinality": "A String", # The field cardinality.

6515

"jsonName": "A String", # The field JSON name.

6516

"kind": "A String", # The field type.

6517

"options": [ # The protocol buffer options.

6518

{ # A protocol buffer option, which can be attached to a message, field,

6519

# enumeration, etc.

6520

"value": { # The option's value packed in an Any message. If the value is a primitive,

6521

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6522

# should be used. If the value is an enum, it should be stored as an int32

6523

# value using the google.protobuf.Int32Value type.

6524

"a_key": "", # Properties of the object. Contains field @type with type URL.

6525

},

6526

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6527

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6528

# For custom options, it should be the fully-qualified name. For example,

6529

# `"google.api.http"`.

6530

},

6531

],

6532

"number": 42, # The field number.

6533

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6534

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6535

"options": [ # The protocol buffer options.

6536

{ # A protocol buffer option, which can be attached to a message, field,

6537

# enumeration, etc.

6538

"value": { # The option's value packed in an Any message. If the value is a primitive,

6539

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6540

# should be used. If the value is an enum, it should be stored as an int32

6541

# value using the google.protobuf.Int32Value type.

6542

"a_key": "", # Properties of the object. Contains field @type with type URL.

6543

},

6544

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6545

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6546

# For custom options, it should be the fully-qualified name. For example,

6547

# `"google.api.http"`.

6548

},

6549

],

6550

"syntax": "A String", # The source syntax.

6551

"name": "A String", # The fully qualified message name.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6552

},

6553

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6554

"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]

6555

# HttpRule, each specifying the mapping of an RPC method

6556

# to one or more HTTP REST API methods.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6557

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

6558

# cases of single segment matches in reserved expansion, where "%2F" will be

6559

# left encoded.

6560

#

6561

# The default behavior is to not decode RFC 6570 reserved characters in multi

6562

# segment matches.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6563

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

6564

#

6565

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6566

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6567

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6568

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

6569

# more HTTP REST endpoints. It allows developers to build a single API service

6570

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

6571

# APIs](https://github.com/googleapis/googleapis),

6572

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

6573

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

6574

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

6575

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6576

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6577

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

6578

# how different portions of the gRPC request message are mapped to the URL

6579

# path, URL query parameters, and HTTP request body. It also controls how the

6580

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

6581

# typically specified as an `google.api.http` annotation on the gRPC method.

6582

#

6583

# Each mapping specifies a URL path template and an HTTP method. The path

6584

# template may refer to one or more fields in the gRPC request message, as long

6585

# as each field is a non-repeated field with a primitive (non-message) type.

6586

# The path template controls how fields of the request message are mapped to

6587

# the URL path.

6588

#

6589

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6590

#

6591

# service Messaging {

6592

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6593

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6594

# get: "/v1/{name=messages/*}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6595

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6596

# }

6597

# }

6598

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6599

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6600

# }

6601

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6602

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6603

# }

6604

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6605

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6606

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6607

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6608

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6609

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6610

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6611

# Any fields in the request message which are not bound by the path template

6612

# automatically become HTTP query parameters if there is no HTTP request body.

6613

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6614

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6615

# service Messaging {

6616

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6617

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6618

# get:"/v1/messages/{message_id}"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6619

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6620

# }

6621

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6622

# message GetMessageRequest {

6623

# message SubMessage {

6624

# string subfield = 1;

6625

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6626

# string message_id = 1; // Mapped to URL path.

6627

# int64 revision = 2; // Mapped to URL query parameter `revision`.

6628

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6629

# }

6630

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6631

# This enables a HTTP JSON to RPC mapping as below:

6632

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6633

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6634

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6635

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6636

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

6637

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6638

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6639

# Note that fields which are mapped to URL query parameters must have a

6640

# primitive type or a repeated primitive type or a non-repeated message type.

6641

# 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]

6642

# 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]

6643

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

6644

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6645

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6646

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6647

# specifies the mapping. Consider a REST update method on the

6648

# message resource collection:

6649

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6650

# service Messaging {

6651

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

6652

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6653

# patch: "/v1/messages/{message_id}"

6654

# body: "message"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message UpdateMessageRequest {

6659

# string message_id = 1; // mapped to the URL

6660

# Message message = 2; // mapped to the body

6661

# }

6662

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6663

# The following HTTP JSON to RPC mapping is enabled, where the

6664

# representation of the JSON in the request body is determined by

6665

# protos JSON encoding:

6666

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6667

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6668

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6669

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6670

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6671

#

6672

# The special name `*` can be used in the body mapping to define that

6673

# every field not bound by the path template should be mapped to the

6674

# request body. This enables the following alternative definition of

6675

# the update method:

6676

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6677

# service Messaging {

6678

# rpc UpdateMessage(Message) returns (Message) {

6679

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6680

# patch: "/v1/messages/{message_id}"

6681

# body: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# };

# }

# }

# message Message {

# string message_id = 1;

6687

# string text = 2;

6688

# }

6689

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6690

#

6691

# The following HTTP JSON to RPC mapping is enabled:

6692

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6693

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6694

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6695

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6696

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6697

#

6698

# Note that when using `*` in the body mapping, it is not possible to

6699

# 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]

6700

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6701

# defining REST APIs. The common usage of `*` is in custom methods

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6702

# which don't use the URL at all for transferring data.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6703

#

6704

# It is possible to define multiple HTTP methods for one RPC by using

6705

# the `additional_bindings` option. Example:

6706

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6707

# service Messaging {

6708

# rpc GetMessage(GetMessageRequest) returns (Message) {

6709

# option (google.api.http) = {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6710

# get: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6711

# additional_bindings {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6712

# get: "/v1/users/{user_id}/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6713

# }

6714

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6715

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6716

# }

6717

# message GetMessageRequest {

6718

# string message_id = 1;

6719

# string user_id = 2;

6720

# }

6721

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6722

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6723

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6724

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6725

# -----|-----

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6726

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

6727

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

6728

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6729

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6730

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6731

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6732

# 1. Leaf request fields (recursive expansion nested messages in the request

6733

# message) are classified into three categories:

6734

# - Fields referred by the path template. They are passed via the URL path.

6735

# - Fields referred by the HttpRule.body. They are passed via the HTTP

6736

# request body.

6737

# - All other fields are passed via the URL query parameters, and the

6738

# parameter name is the field path in the request message. A repeated

6739

# field can be represented as multiple query parameters under the same

6740

# name.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6741

# 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]

6742

# are passed via URL path and HTTP request body.

6743

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

6744

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6745

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6746

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6747

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6748

# Template = "/" Segments [ Verb ] ;

6749

# Segments = Segment { "/" Segment } ;

6750

# Segment = "*" | "**" | LITERAL | Variable ;

6751

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

6752

# FieldPath = IDENT { "." IDENT } ;

6753

# Verb = ":" LITERAL ;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6754

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6755

# The syntax `*` matches a single URL path segment. The syntax `**` matches

6756

# zero or more URL path segments, which must be the last part of the URL path

6757

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6758

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6759

# The syntax `Variable` matches part of the URL path as specified by its

6760

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6761

# matches a single path segment, its template may be omitted, e.g. `{var}`

6762

# is equivalent to `{var=*}`.

6763

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6764

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

6765

# contains any reserved character, such characters should be percent-encoded

6766

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6767

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6768

# If a variable contains exactly one path segment, such as `"{var}"` or

6769

# `"{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]

6770

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

6771

# server side does the reverse decoding. Such variables show up in the

6772

# [Discovery

6773

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6774

# `{var}`.

6775

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6776

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

6777

# 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]

6778

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6779

# 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]

6780

# unchanged. Such variables show up in the

6781

# [Discovery

6782

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6783

# `{+var}`.

6784

#

6785

# ## Using gRPC API Service Configuration

6786

#

6787

# gRPC API Service Configuration (service config) is a configuration language

6788

# for configuring a gRPC service to become a user-facing product. The

6789

# service config is simply the YAML representation of the `google.api.Service`

6790

# proto message.

6791

#

6792

# As an alternative to annotating your proto file, you can configure gRPC

6793

# transcoding in your service config YAML files. You do this by specifying a

6794

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

6795

# effect as the proto annotation. This can be particularly useful if you

6796

# have a proto that is reused in multiple services. Note that any transcoding

6797

# specified in the service config will override any matching transcoding

6798

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

6805

# - selector: example.v1.Messaging.GetMessage

6806

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

6811

# proto to JSON conversion must follow the [proto3

6812

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

6813

#

6814

# While the single segment variable follows the semantics of

6815

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

6816

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

6817

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

6818

# does not expand special characters like `?` and `#`, which would lead

6819

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

6820

# for multi segment variables.

6821

#

6822

# The path variables **must not** refer to any repeated or mapped field,

6823

# because client libraries are not capable of handling such variable expansion.

6824

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

6825

# The path variables **must not** capture the leading "/" character. The reason

6826

# 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]

6827

# character. For consistency, all path variables must share the same behavior.

6828

#

6829

# Repeated message fields must not be mapped to URL query parameters, because

6830

# no client library can support such complicated mapping.

6831

#

6832

# If an API needs to use a JSON array for request or response body, it can map

6833

# the request or response body to a repeated field. However, some gRPC

6834

# Transcoding implementations may not support this feature.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6835

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6836

"selector": "A String", # Selects a method to which this rule applies.

6837

#

6838

# Refer to selector for syntax details.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6839

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

6840

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

6841

# response body. When omitted, the entire response message will be used

6842

# as the HTTP response body.

6843

#

6844

# NOTE: The referred field must be present at the top-level of the response

6845

# message type.

6846

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

6847

# body, or `*` for mapping all request fields not captured by the path

6848

# pattern to the HTTP body, or omitted for not having any HTTP request body.

6849

#

6850

# NOTE: the referred field must be present at the top-level of the request

6851

# message type.

6852

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

6853

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

6854

# not contain an `additional_bindings` field themselves (that is,

6855

# the nesting may only be one level deep).

6856

# Object with schema name: HttpRule

6857

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6858

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

6859

# included in the `pattern` field, such as HEAD, or "*" to leave the

6860

# HTTP method unspecified for this rule. The wild-card rule is useful

6861

# for services that provide content to Web (HTML) clients.

6862

"path": "A String", # The path matched by this custom verb.

6863

"kind": "A String", # The name of this custom HTTP verb.

6864

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6865

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

6866

# half-duplex streaming method.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6867

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6868

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

6869

# resources.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6870

},

6871

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6872

},

6873

"logs": [ # Defines the logs used by this service.

6874

{ # A description of a log type. Example in YAML format:

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6875

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6876

# - name: library.googleapis.com/activity_history

6877

# description: The history of borrowing and returning library items.

6878

# display_name: Activity

6879

# labels:

6880

# - key: /customer_id

6881

# description: Identifier of a library customer

6882

"description": "A String", # A human-readable description of this log. This information appears in

6883

# the documentation and can contain details.

6884

"labels": [ # The set of labels that are available to describe a specific log entry.

6885

# Runtime requests that contain labels not specified here are

6886

# considered invalid.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6887

{ # A description of a label.

6888

"valueType": "A String", # The type of data that can be assigned to the label.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6889

"description": "A String", # A human-readable description for the label.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6890

"key": "A String", # The label key.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6891

},

6892

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6893

"displayName": "A String", # The human-readable name for this log. This information appears on

6894

# the user interface and should be concise.

6895

"name": "A String", # The name of the log. It must be less than 512 characters long and can

6896

# include the following characters: upper- and lower-case alphanumeric

6897

# characters [A-Za-z0-9], and punctuation characters including

6898

# slash, underscore, hyphen, period [/_-.].

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

6899

},

6900

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

6901

"metrics": [ # Defines the metrics used by this service.

6902

{ # Defines a metric type and its schema. Once a metric descriptor is created,

6903

# deleting or altering it stops data collection and makes the metric type's

6904

# existing data unusable.

6905

#

6906

# The following are specific rules for service defined Monitoring metric

6907

# descriptors:

6908

#

6909

# * `type`, `metric_kind`, `value_type`, `description`, and `display_name`

6910

# fields are all required. The `unit` field must be specified

6911

# if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.

6912

# * Maximum of default 500 metric descriptors per service is allowed.

6913

# * Maximum of default 10 labels per metric descriptor is allowed.

6914

#

6915

# The default maximum limit can be overridden. Please follow

6916

# https://cloud.google.com/monitoring/quotas

6917

"unit": "A String", # The units in which the metric value is reported. It is only applicable

6918

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

6919

# defines the representation of the stored metric values.

6920

#

6921

# Different systems may scale the values to be more easily displayed (so a

6922

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

6923

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

6924

# `KBy`, then the value of the metric is always in thousands of bytes, no

6925

# matter how it may be displayed..

6926

#

6927

# If you want a custom metric to record the exact number of CPU-seconds used

6928

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

6929

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

6930

# CPU-seconds, then the value is written as `12005`.

6931

#

6932

# Alternatively, if you want a custom metric to record data in a more

6933

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

6934

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

6935

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

6936

#

6937

# The supported units are a subset of [The Unified Code for Units of

6938

# Measure](http://unitsofmeasure.org/ucum.html) standard:

6939

#

6940

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

# * `1` dimensionless

6949

#

6950

# **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)

6959

# * `Y` yotta (10^24)

6960

#

6961

# * `m` milli (10^-3)

6962

# * `u` micro (10^-6)

6963

# * `n` nano (10^-9)

6964

# * `p` pico (10^-12)

6965

# * `f` femto (10^-15)

6966

# * `a` atto (10^-18)

6967

# * `z` zepto (10^-21)

6968

# * `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:

6979

#

6980

# * `/` division or ratio (as an infix operator). For examples,

6981

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

6982

# have `/s` in a metric `unit`; rates should always be computed at

6983

# query time from the underlying cumulative or delta value).

6984

# * `.` multiplication or composition (as an infix operator). For

6985

# examples, `GBy.d` or `k{watt}.h`.

6986

#

6987

# The grammar for a unit is as follows:

6988

#

6989

# Expression = Component { "." Component } { "/" Component } ;

6990

#

6991

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

7001

# is used alone, then the unit is equivalent to `1`. For examples,

7002

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

7003

# * `NAME` is a sequence of non-blank printable ASCII characters not

7004

# containing `{` or `}`.

7005

# * `1` represents a unitary [dimensionless

7006

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

7007

# as in `1/s`. It is typically used when none of the basic units are

7008

# appropriate. For example, "new users per day" can be represented as

7009

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

7010

# users). Alternatively, "thousands of page views per day" would be

7011

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

7012

# value of `5.3` would mean "5300 page views per day").

7013

# * `%` represents dimensionless value of 1/100, and annotates values giving

7014

# a percentage (so the metric values are typically in the range of 0..100,

7015

# and a metric value `3` means "3 percent").

7016

# * `10^2.%` indicates a metric contains a ratio, typically in the range

7017

# 0..1, that will be multiplied by 100 and displayed as a percentage

7018

# (so a metric value `0.03` means "3 percent").

7019

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

7020

# Use sentence case without an ending period, for example "Request count".

7021

# This field is optional but it is recommended to be set for any metrics

7022

# associated with user-visible concepts, such as Quota.

7023

"monitoredResourceTypes": [ # Read-only. If present, then a time

7024

# series, which is identified partially by

7025

# a metric type and a MonitoredResourceDescriptor, that is associated

7026

# with this metric type can only be associated with one of the monitored

7027

# resource types listed here.

7028

"A String",

7029

],

7030

"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.

7031

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

7032

# periodically, consecutive data points are stored at this time interval,

7033

# excluding data loss due to errors. Metrics with a higher granularity have

7034

# a smaller sampling period.

7035

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

7036

# age are guaranteed to be ingested and available to be read, excluding

7037

# data loss due to errors.

7038

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7039

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7040

"name": "A String", # The resource name of the metric descriptor.

7041

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

7042

# Some combinations of `metric_kind` and `value_type` might not be supported.

7043

"launchStage": "A String", # Optional. The launch stage of the metric definition.

7044

"type": "A String", # The metric type, including its DNS name prefix. The type is not

7045

# URL-encoded.

7046

#

7047

# All service defined metrics must be prefixed with the service name, in the

7048

# format of `{service name}/{relative metric name}`, such as

7049

# `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric

7050

# name must follow:

7051

#

7052

# * Only upper and lower-case letters, digits, '/' and underscores '_' are

7053

# allowed.

7054

# * The maximum number of characters allowed for the relative_metric_name is

7055

# 100.

7056

#

7057

# All user-defined metric types have the DNS name

7058

# `custom.googleapis.com`, `external.googleapis.com`, or

7059

# `logging.googleapis.com/user/`.

7060

#

7061

# Metric types should use a natural hierarchical grouping. For example:

7062

#

7063

# "custom.googleapis.com/invoice/paid/amount"

7064

# "external.googleapis.com/prometheus/up"

7065

# "appengine.googleapis.com/http/server/response_latencies"

7066

"description": "A String", # A detailed description of the metric, which can be used in documentation.

7067

"labels": [ # The set of labels that can be used to describe a specific

7068

# instance of this metric type.

7069

#

7070

# The label key name must follow:

7071

#

7072

# * Only upper and lower-case letters, digits and underscores (_) are

7073

# allowed.

7074

# * Label name must start with a letter or digit.

7075

# * The maximum length of a label name is 100 characters.

7076

#

7077

# For example, the

7078

# `appengine.googleapis.com/http/server/response_latencies` metric

7079

# type has a label for the HTTP response code, `response_code`, so

7080

# you can look at latencies for successful responses or just

7081

# for responses that failed.

7082

{ # A description of a label.

7083

"valueType": "A String", # The type of data that can be assigned to the label.

7084

"description": "A String", # A human-readable description for the label.

7085

"key": "A String", # The label key.

7086

},

7087

],

7088

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

7089

# Some combinations of `metric_kind` and `value_type` might not be supported.

7090

},

7091

],

7092

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7093

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7094

# Example:

7095

# <pre><code>documentation:

7096

# summary: >

7097

# The Google Calendar API gives access

7098

# to most calendar features.

7099

# pages:

7100

# - name: Overview

7101

# content: &#40;== include google/foo/overview.md ==&#41;

7102

# - name: Tutorial

7103

# content: &#40;== include google/foo/tutorial.md ==&#41;

7104

# subpages;

7105

# - name: Java

7106

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

7107

# rules:

7108

# - selector: google.calendar.Calendar.Get

7109

# description: >

7110

# ...

7111

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

7116

# standard markdown features, definition lists, tables and fenced

7117

# code blocks are supported. Section headers can be provided and are

7118

# interpreted relative to the section nesting of the context where

7119

# a documentation fragment is embedded.

7120

#

7121

# Documentation from the IDL is merged with documentation defined

7122

# via the config at normalization time, where documentation provided

7123

# by config rules overrides IDL provided.

7124

#

7125

# A number of constructs specific to the API platform are supported

7126

# in documentation text.

7127

#

7128

# In order to reference a proto element, the following

7129

# notation can be used:

7130

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

7131

# To override the display text used for the link, this can be used:

7132

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

7133

# Text can be excluded from doc using the following notation:

7134

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

7135

#

7136

# A few directives are available in documentation. Note that

7137

# directives must appear on a single line to be properly

7138

# identified. The `include` directive includes a markdown file from

7139

# an external source:

7140

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

7141

# The `resource_for` directive marks a message to be the resource of

7142

# a collection in REST view. If it is not specified, tools attempt

7143

# to infer the resource from the operations in a collection:

7144

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

7145

# The directive `suppress_warning` does not directly affect documentation

7146

# and is documented together with service config validation.

7147

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

7148

# from the yaml file) is not suitable. This can be seen in any fully

7149

# specified service urls as well as sections that show a base that other

7150

# urls are relative to.

7151

"overview": "A String", # Declares a single overview page. For example:

7152

# <pre><code>documentation:

7153

# summary: ...

7154

# overview: &#40;== include overview.md ==&#41;

7155

# </code></pre>

7156

# This is a shortcut for the following declaration (using pages style):

7157

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: &#40;== include overview.md ==&#41;

7162

# </code></pre>

7163

# Note: you cannot specify both `overview` field and `pages` field.

7164

"documentationRootUrl": "A String", # The URL to the root of documentation.

7165

"rules": [ # A list of documentation rules that apply to individual API elements.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7166

#

7167

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7168

{ # A documentation rule provides information about individual API elements.

7169

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

7170

# an element is marked as `deprecated`.

7171

"description": "A String", # Description of the selected API(s).

7172

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

7173

# qualified name of the element which may end in "*", indicating a wildcard.

7174

# Wildcards are only allowed at the end and for a whole component of the

7175

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

7176

# wildcard will match one or more components. To specify a default for all

7177

# applicable elements, the whole pattern "*" is used.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7178

},

7179

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7180

"pages": [ # The top level pages for the documentation set.

7181

{ # Represents a documentation page. A page can contain subpages to represent

7182

# nested documentation set structure.

7183

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

7184

# ==&#41;</code> to include content from a Markdown file.

7185

"name": "A String", # The name of the page. It will be used as an identity of the page to

7186

# generate URI of the page, text of the link to this page in navigation,

7187

# etc. The full page name (start from the root page name to this page

7188

# concatenated with `.`) can be used as reference to the page in your

7189

# documentation. For example:

7190

# <pre><code>pages:

7191

# - name: Tutorial

7192

# content: &#40;== include tutorial.md ==&#41;

7193

# subpages:

7194

# - name: Java

7195

# content: &#40;== include tutorial_java.md ==&#41;

7196

# </code></pre>

7197

# You can reference `Java` page using Markdown reference link syntax:

7198

# `Java`.

7199

"subpages": [ # Subpages of this page. The order of subpages specified here will be

7200

# honored in the generated docset.

7201

# Object with schema name: Page

],

},

],

"summary": "A String", # A short summary of what the service does. Can only be provided by

7206

# plain text.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7207

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7208

"configVersion": 42, # The semantic version of the service configuration. The config version

7209

# affects the interpretation of the service configuration. For example,

7210

# certain features are enabled by default for certain config versions.

7211

#

7212

# The latest config version is `3`.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7213

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

7214

# usage.

7215

#

7216

# The metric based quota configuration works this way:

7217

# - The service configuration defines a set of metrics.

7218

# - For API calls, the quota.metric_rules maps methods to metrics with

7219

# corresponding costs.

7220

# - The quota.limits defines limits on the metrics, which will be used for

7221

# quota checks at runtime.

7222

#

7223

# An example quota configuration in yaml format:

#

# quota:

# limits:

#

# - name: apiWriteQpsPerProject

7229

# metric: library.googleapis.com/write_calls

7230

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

7236

# # except for the UpdateBook and DeleteBook methods. These two methods

7237

# # are mapped to the write_calls metric, with the UpdateBook method

7238

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

7243

# - selector: google.example.library.v1.LibraryService.UpdateBook

7244

# metric_costs:

7245

# library.googleapis.com/write_calls: 2

7246

# - selector: google.example.library.v1.LibraryService.DeleteBook

7247

# metric_costs:

7248

# library.googleapis.com/write_calls: 1

7249

#

7250

# Corresponding Metric definition:

7251

#

7252

# metrics:

7253

# - name: library.googleapis.com/read_calls

7254

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

7259

# display_name: Write requests

7260

# metric_kind: DELTA

7261

# value_type: INT64

7262

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7263

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

7264

# or more metrics.

7265

{ # Bind API methods to metrics. Binding a method to a metric causes that

7266

# metric's configured quota behaviors to apply to the method call.

7267

"selector": "A String", # Selects the methods to which this rule applies.

7268

#

7269

# Refer to selector for syntax details.

7270

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

7271

# cost applied to each metric.

7272

#

7273

# The key of the map is the metric name, and the values are the amount

7274

# increased for the metric against which the quota limits are defined.

7275

# The value must not be negative.

"a_key": "A String",

},

},

],

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7280

"limits": [ # List of `QuotaLimit` definitions for the service.

7281

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

7282

# for a limit type. There can be at most one limit for a duration and limit

7283

# type combination defined within a `QuotaGroup`.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7284

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

7285

# integer value that is the maximum number of requests allowed for the

7286

# specified unit. Currently only STANDARD is supported.

7287

"a_key": "A String",

7288

},

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7289

"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]

7290

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7291

# Used by group-based quotas only.

7292

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

7293

# The free tier is the number of tokens that will be subtracted from the

7294

# billed amount when billing is enabled.

7295

# This field can only be set on a limit with duration "1d", in a billable

7296

# group; it is invalid on any other limit. If this field is not set, it

7297

# 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]

7298

#

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7299

# Used by group-based quotas only.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7300

"displayName": "A String", # User-visible display name for this limit.

7301

# Optional. If not set, the UI will provide a default display name based on

7302

# the quota configuration. This field can be used to override the default

7303

# display name generated from the configuration.

7304

"description": "A String", # Optional. User-visible, extended description for this quota limit.

7305

# Should be used only when more context is needed to understand this limit

7306

# than provided by the limit's display name (see: `display_name`).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7307

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

7308

# duration. This is the number of tokens assigned when a client

7309

# application developer activates the service for his/her project.

7310

#

7311

# Specifying a value of 0 will block all requests. This can be used if you

7312

# are provisioning quota to selected consumers and blocking others.

7313

# Similarly, a value of -1 will indicate an unlimited quota. No other

7314

# negative values are allowed.

7315

#

7316

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7317

"name": "A String", # Name of the quota limit.

7318

#

7319

# The name must be provided, and it must be unique within the service. The

7320

# name can only include alphanumeric characters as well as '-'.

7321

#

7322

# The maximum length of the limit name is 64 characters.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7323

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

7324

# duration. Client application developers can override the default limit up

7325

# to this maximum. If specified, this value cannot be set to a value less

7326

# than the default limit. If not specified, it is set to the default limit.

7327

#

7328

# To allow clients to apply overrides with no upper bound, set this to -1,

7329

# indicating unlimited maximum quota.

7330

#

7331

# Used by group-based quotas only.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7332

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

7333

# the same metric will be checked together during runtime. The metric must be

7334

# defined within the service config.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7335

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

7336

# Metric.unit. The supported unit kinds are determined by the quota

7337

# backend system.

7338

#

7339

# Here are some examples:

7340

# * "1/min/{project}" for quota per minute per project.

7341

#

7342

# Note: the order of unit components is insignificant.

7343

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7344

},

7345

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7346

},

7347

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

7348

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

7356

# - google.foo.v1.AnotherError

7357

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

7358

"A String",

7359

],

7360

"rules": [ # The list of custom error rules that apply to individual API messages.

7361

#

7362

# **NOTE:** All service configuration rules follow "last one wins" order.

7363

{ # A custom error rule.

7364

"selector": "A String", # Selects messages to which this rule applies.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7365

#

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7366

# Refer to selector for syntax details.

7367

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

7368

# objects of this type will be filtered when they appear in error payload.

},

],

},

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

7373

#

7374

# Example for an API targeted for external use:

7375

#

7376

# name: calendar.googleapis.com

7377

# authentication:

7378

# providers:

7379

# - id: google_calendar_auth

7380

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

7381

# issuer: https://securetoken.google.com

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

7386

"rules": [ # A list of authentication rules that apply to individual API methods.

7387

#

7388

# **NOTE:** All service configuration rules follow "last one wins" order.

7389

{ # Authentication rules for the service.

7390

#

7391

# By default, if a method has any authentication requirements, every request

7392

# must include a valid credential matching one of the requirements.

7393

# It's an error to include more than one kind of credential in a single

7394

# request.

7395

#

7396

# If a method doesn't have any auth requirements, request credentials will be

7397

# ignored.

7398

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

7399

# there are scopes defined for "Read-only access to Google Calendar" and

7400

# "Access to Cloud Platform". Users can consent to a scope for an application,

7401

# giving it permission to access that data on their behalf.

7402

#

7403

# OAuth scope specifications should be fairly coarse grained; a user will need

7404

# to see and understand the text description of what your scope means.

7405

#

7406

# In most cases: use one or at most two OAuth scopes for an entire family of

7407

# products. If your product has multiple APIs, you should probably be sharing

7408

# the OAuth scope across all of those APIs.

7409

#

7410

# When you need finer grained OAuth consent screens: talk with your product

7411

# management about how developers will use them in practice.

7412

#

7413

# Please note that even though each of the canonical scopes is enough for a

7414

# request to be accepted and passed to the backend, a request can still fail

7415

# due to the backend requiring additional scopes or permissions.

7416

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

7417

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

7422

# https://www.googleapis.com/auth/calendar.read

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7423

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7424

"requirements": [ # Requirements for additional authentication providers.

7425

{ # User-defined authentication requirements, including support for

7426

# [JSON Web Token

7427

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

7428

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

7433

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

7434

# implemented and accepted in all the runtime components.

7435

#

7436

# The list of JWT

7437

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

7438

# that are allowed to access. A JWT containing any of these audiences will

7439

# be accepted. When this setting is absent, only JWTs with audience

7440

# "https://Service_name/API_name"

7441

# will be accepted. For example, if no audiences are in the setting,

7442

# LibraryService API will only accept JWTs with the following audience

7443

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

7448

# bookstore_web.apps.googleusercontent.com

7449

},

7450

],

7451

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7452

"selector": "A String", # Selects the methods to which this rule applies.

7453

#

7454

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7455

},

7456

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7457

"providers": [ # Defines a set of authentication providers that a service supports.

7458

{ # Configuration for an authentication provider, including support for

7459

# [JSON Web Token

7460

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

7461

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

7462

# `AuthRequirement.provider_id`.

7463

#

7464

# Example: "bookstore_auth".

7465

"issuer": "A String", # Identifies the principal that issued the JWT. See

7466

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

7467

# Usually a URL or an email address.

7468

#

7469

# Example: https://securetoken.google.com

7470

# Example: 1234567-compute@developer.gserviceaccount.com

7471

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

7472

# [OpenID

7473

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

7474

# Optional if the key set document:

7475

# - can be retrieved from

7476

# [OpenID

7477

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

7478

# the issuer.

7479

# - can be inferred from the email domain of the issuer (e.g. a Google

7480

# service account).

7481

#

7482

# Example: https://www.googleapis.com/oauth2/v1/certs

7483

"audiences": "A String", # The list of JWT

7484

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

7485

# that are allowed to access. A JWT containing any of these audiences will

7486

# be accepted. When this setting is absent, JWTs with audiences:

7487

# - "https://[service.name]/[google.protobuf.Api.name]"

7488

# - "https://[service.name]/"

7489

# will be accepted.

7490

# For example, if no audiences are in the setting, LibraryService API will

7491

# accept JWTs with the following audiences:

7492

# -

7493

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

7494

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

7499

# bookstore_web.apps.googleusercontent.com

7500

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

7501

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

7502

"jwtLocations": [ # Defines the locations to extract the JWT.

7503

#

7504

# JWT locations can be either from HTTP headers or URL query parameters.

7505

# The rule is that the first match wins. The checking order is: checking

7506

# all headers first, then URL query parameters.

7507

#

7508

# If not specified, default to use following 3 locations:

7509

# 1) Authorization: Bearer

7510

# 2) x-goog-iap-jwt-assertion

7511

# 3) access_token query parameter

7512

#

7513

# Default locations can be specified as followings:

7514

# jwt_locations:

7515

# - header: Authorization

7516

# value_prefix: "Bearer "

7517

# - header: x-goog-iap-jwt-assertion

7518

# - query: access_token

7519

{ # Specifies a location to extract JWT from an API request.

7520

"query": "A String", # Specifies URL query parameter name to extract JWT token.

7521

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

7522

# Only applies to "in" header type. Must be empty for "in" query type.

7523

# If not empty, the header value has to match (case sensitive) this prefix.

7524

# If not matched, JWT will not be extracted. If matched, JWT will be

7525

# extracted after the prefix is removed.

7526

#

7527

# For example, for "Authorization: Bearer {JWT}",

7528

# value_prefix="Bearer " with a space at the end.

7529

"header": "A String", # Specifies HTTP header name to extract JWT token.

},

],

},

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7534

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7535

"title": "A String", # The product title for this service.

7536

"producerProjectId": "A String", # The Google project that owns this service.

7537

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

7538

# of the google.protobuf.Api needs to be provided by the configuration

7539

# author, as the remaining fields will be derived from the IDL during the

7540

# normalization process. It is an error to specify an API interface here

7541

# which cannot be resolved against the associated IDL files.

7542

{ # Api is a light-weight descriptor for an API Interface.

7543

#

7544

# Interfaces are also described as "protocol buffer services" in some contexts,

7545

# such as by the "service" keyword in a .proto file, but they are different

7546

# from API Services, which represent a concrete implementation of an interface

7547

# as opposed to simply a description of methods and bindings. They are also

7548

# sometimes simply referred to as "APIs" in other contexts, such as the name of

7549

# this message itself. See https://cloud.google.com/apis/design/glossary for

7550

# detailed terminology.

7551

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

7552

# message.

7553

# protobuf element, like the file in which it is defined.

7554

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7555

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

7556

},

7557

"syntax": "A String", # The source syntax of the service.

7558

"methods": [ # The methods of this interface, in unspecified order.

7559

{ # Method represents a method of an API interface.

7560

"options": [ # Any metadata attached to the method.

7561

{ # A protocol buffer option, which can be attached to a message, field,

7562

# enumeration, etc.

7563

"value": { # The option's value packed in an Any message. If the value is a primitive,

7564

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7565

# should be used. If the value is an enum, it should be stored as an int32

7566

# value using the google.protobuf.Int32Value type.

7567

"a_key": "", # Properties of the object. Contains field @type with type URL.

7568

},

7569

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7570

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7571

# For custom options, it should be the fully-qualified name. For example,

7572

# `"google.api.http"`.

7573

},

7574

],

7575

"responseStreaming": True or False, # If true, the response is streamed.

7576

"syntax": "A String", # The source syntax of this method.

7577

"requestTypeUrl": "A String", # A URL of the input message type.

7578

"name": "A String", # The simple name of this method.

7579

"responseTypeUrl": "A String", # The URL of the output message type.

7580

"requestStreaming": True or False, # If true, the request is streamed.

7581

},

7582

],

7583

"name": "A String", # The fully qualified name of this interface, including package name

7584

# followed by the interface's simple name.

7585

"version": "A String", # A version string for this interface. If specified, must have the form

7586

# `major-version.minor-version`, as in `1.10`. If the minor version is

7587

# omitted, it defaults to zero. If the entire version field is empty, the

7588

# major version is derived from the package name, as outlined below. If the

7589

# field is not empty, the version in the package name will be verified to be

7590

# consistent with what is provided here.

7591

#

7592

# The versioning schema uses [semantic

7593

# versioning](http://semver.org) where the major version number

7594

# indicates a breaking change and the minor version an additive,

7595

# non-breaking change. Both version numbers are signals to users

7596

# what to expect from different versions, and should be carefully

7597

# chosen based on the product plan.

7598

#

7599

# The major version is also reflected in the package name of the

7600

# interface, which must end in `v<major-version>`, as in

7601

# `google.feature.v1`. For major versions 0 and 1, the suffix can

7602

# be omitted. Zero major versions must only be used for

7603

# experimental, non-GA interfaces.

7604

"options": [ # Any metadata attached to the interface.

7605

{ # A protocol buffer option, which can be attached to a message, field,

7606

# enumeration, etc.

7607

"value": { # The option's value packed in an Any message. If the value is a primitive,

7608

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7609

# should be used. If the value is an enum, it should be stored as an int32

7610

# value using the google.protobuf.Int32Value type.

7611

"a_key": "", # Properties of the object. Contains field @type with type URL.

7612

},

7613

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7614

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7615

# For custom options, it should be the fully-qualified name. For example,

7616

# `"google.api.http"`.

7617

},

7618

],

7619

"mixins": [ # Included interfaces. See Mixin.

7620

{ # Declares an API Interface to be included in this interface. The including

7621

# interface must redeclare all the methods from the included interface, but

7622

# documentation and options are inherited as follows:

7623

#

7624

# - If after comment and whitespace stripping, the documentation

7625

# string of the redeclared method is empty, it will be inherited

7626

# from the original method.

7627

#

7628

# - Each annotation belonging to the service config (http,

7629

# visibility) which is not set in the redeclared method will be

7630

# inherited.

7631

#

7632

# - If an http annotation is inherited, the path pattern will be

7633

# modified as follows. Any version prefix will be replaced by the

7634

# version of the including interface plus the root path if

7635

# specified.

7636

#

7637

# Example of a simple mixin:

7638

#

7639

# package google.acl.v1;

7640

# service AccessControl {

7641

# // Get the underlying ACL object.

7642

# rpc GetAcl(GetAclRequest) returns (Acl) {

7643

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

7648

# service Storage {

7649

# // rpc GetAcl(GetAclRequest) returns (Acl);

7650

#

7651

# // Get a data record.

7652

# rpc GetData(GetDataRequest) returns (Data) {

7653

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

7658

#

7659

# apis:

7660

# - name: google.storage.v2.Storage

7661

# mixins:

7662

# - name: google.acl.v1.AccessControl

7663

#

7664

# The mixin construct implies that all methods in `AccessControl` are

7665

# also declared with same name and request/response types in

7666

# `Storage`. A documentation generator or annotation processor will

7667

# see the effective `Storage.GetAcl` method after inherting

7668

# documentation and annotations as follows:

7669

#

7670

# service Storage {

7671

# // Get the underlying ACL object.

7672

# rpc GetAcl(GetAclRequest) returns (Acl) {

7673

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

7679

#

7680

# If the `root` field in the mixin is specified, it should be a

7681

# relative path under which inherited HTTP paths are placed. Example:

7682

#

7683

# apis:

7684

# - name: google.storage.v2.Storage

7685

# mixins:

7686

# - name: google.acl.v1.AccessControl

7687

# root: acls

7688

#

7689

# This implies the following inherited HTTP annotation:

7690

#

7691

# service Storage {

7692

# // Get the underlying ACL object.

7693

# rpc GetAcl(GetAclRequest) returns (Acl) {

7694

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

7699

# are rooted.

7700

"name": "A String", # The fully qualified name of the interface which is included.

},

],

},

],

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7706

# by the client for tracking purpose. Must be no longer than 63 characters

7707

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

7708

# empty, the server may choose to generate one instead.

7709

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

7710

# with the same name as the service is automatically generated to service all

7711

# defined APIs.

7712

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

7713

# A service may expose any number of endpoints, and all endpoints share the

7714

# same service configuration, such as quota configuration and monitoring

7715

# configuration.

7716

#

7717

# Example service configuration:

7718

#

7719

# name: library-example.googleapis.com

7720

# endpoints:

7721

# # Below entry makes 'google.example.library.v1.Library'

7722

# # API be served from endpoint address library-example.googleapis.com.

7723

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

7724

# # it to decide whether the subsequent cross-origin request is

7725

# # allowed to proceed.

7726

# - name: library-example.googleapis.com

7727

# allow_cors: true

7728

"name": "A String", # The canonical name of this endpoint.

7729

"allowCors": True or False, # Allowing

7730

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

7731

# cross-domain traffic, would allow the backends served from this endpoint to

7732

# receive and respond to HTTP OPTIONS requests. The response will be used by

7733

# the browser to determine whether the subsequent cross-origin request is

7734

# allowed to proceed.

7735

"target": "A String", # The specification of an Internet routable address of API frontend that will

7736

# handle requests to this [API

7737

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

7738

# either a valid IPv4 address or a fully-qualified domain name. For example,

7739

# "8.8.8.8" or "myservice.appspot.com".

7740

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

7741

# please specify multiple google.api.Endpoint for each of the intended

7742

# aliases.

7743

#

7744

# Additional names that this endpoint will be hosted on.

"A String",

],

},

],

"systemParameters": { # ### System parameter configuration # System parameter configuration.

7750

#

7751

# A system parameter is a special kind of parameter defined by the API

7752

# system, not by an individual API. It is typically mapped to an HTTP header

7753

# and/or a URL query parameter. This configuration specifies which methods

7754

# change the names of the system parameters.

7755

"rules": [ # Define system parameters.

7756

#

7757

# The parameters defined here will override the default parameters

7758

# implemented by the system. If this field is missing from the service

7759

# config, default system parameters will be used. Default system parameters

7760

# and names is implementation-dependent.

7761

#

7762

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

7770

#

7771

#

7772

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

7777

# parameters:

7778

# - name: api_key

7779

# http_header: Api-Key1

7780

# - name: api_key

7781

# http_header: Api-Key2

7782

#

7783

# **NOTE:** All service configuration rules follow "last one wins" order.

7784

{ # Define a system parameter rule mapping system parameter definitions to

7785

# methods.

7786

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

7787

# For a given method call, only one of them should be used. If multiple

7788

# names are used the behavior is implementation-dependent.

7789

# If none of the specified names are present the behavior is

7790

# parameter-dependent.

7791

{ # Define a parameter's name and location. The parameter may be passed as either

7792

# an HTTP header or a URL query parameter, and if both are passed the behavior

7793

# is implementation-dependent.

7794

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

7795

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

7796

# insensitive.

7797

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

# sensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

7802

# methods in all APIs.

7803

#

7804

# Refer to selector for syntax details.

},

],

},

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

7809

# by the Service.monitoring and Service.logging configurations.

7810

{ # An object that describes the schema of a MonitoredResource object using a

7811

# type name and a set of labels. For example, the monitored resource

7812

# descriptor for Google Compute Engine VM instances has a type of

7813

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

7814

# `"zone"` to identify particular VM instances.

7815

#

7816

# Different services can support different monitored resource types.

7817

#

7818

# The following are specific rules to service defined monitored resources for

7819

# Monitoring and Logging:

7820

#

7821

# * The `type`, `display_name`, `description`, `labels` and `launch_stage`

7822

# fields are all required.

7823

# * The first label of the monitored resource descriptor must be

7824

# `resource_container`. There are legacy monitored resource descritptors

7825

# start with `project_id`.

7826

# * It must include a `location` label.

7827

# * Maximum of default 5 service defined monitored resource descriptors

7828

# is allowed per service.

7829

# * Maximum of default 10 labels per monitored resource is allowed.

7830

#

7831

# The default maximum limit can be overridden. Please follow

7832

# https://cloud.google.com/monitoring/quotas

7833

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

7834

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

7835

# {type} is the value of the `type` field in this object and

7836

# {project_id} is a project ID that provides API-specific context for

7837

# accessing the type. APIs that do not use project information can use the

7838

# resource name format `"monitoredResourceDescriptors/{type}"`.

7839

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

7840

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

7841

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

7842

# without any article or other determiners. For example,

7843

# `"Google Cloud SQL Database"`.

7844

"labels": [ # Required. A set of labels used to describe instances of this monitored

7845

# resource type.

7846

# The label key name must follow:

7847

#

7848

# * Only upper and lower-case letters, digits and underscores (_) are

7849

# allowed.

7850

# * Label name must start with a letter or digit.

7851

# * The maximum length of a label name is 100 characters.

7852

#

7853

# For example, an individual Google Cloud SQL database is

7854

# identified by values for the labels `database_id` and `location`.

7855

{ # A description of a label.

7856

"valueType": "A String", # The type of data that can be assigned to the label.

7857

"description": "A String", # A human-readable description for the label.

7858

"key": "A String", # The label key.

7859

},

7860

],

7861

"description": "A String", # Optional. A detailed description of the monitored resource type that might

7862

# be used in documentation.

7863

"type": "A String", # Required. The monitored resource type. For example, the type

7864

# `cloudsql_database` represents databases in Google Cloud SQL.

7865

#

7866

# All service defined monitored resource types must be prefixed with the

7867

# service name, in the format of `{service name}/{relative resource name}`.

7868

# The relative resource name must follow:

7869

#

7870

# * Only upper and lower-case letters and digits are allowed.

7871

# * It must start with upper case character and is recommended to use Upper

7872

# Camel Case style.

7873

# * The maximum number of characters allowed for the relative_resource_name

7874

# is 100.

7875

#

7876

# Note there are legacy service monitored resources not following this rule.

7877

},

7878

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7879

"context": { # `Context` defines which contexts an API requests. # Context configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7880

#

7881

# Example:

7882

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

7888

# - google.rpc.context.OriginContext

7889

#

7890

# The above specifies that all methods in the API request

7891

# `google.rpc.context.ProjectContext` and

7892

# `google.rpc.context.OriginContext`.

7893

#

7894

# Available context types are defined in package

7895

# `google.rpc.context`.

7896

#

7897

# This also provides mechanism to whitelist any protobuf message extension that

7898

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

7899

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

7900

# 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"

7908

# allowed_request_extensions:

7909

# - google.foo.v1.NewExtension

7910

# allowed_response_extensions:

7911

# - google.foo.v1.NewExtension

7912

#

7913

# You can also specify extension ID instead of fully qualified extension name

7914

# here.

7915

"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]

7916

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7917

# **NOTE:** All service configuration rules follow "last one wins" order.

7918

{ # A context rule provides information about the context for an individual API

7919

# element.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7920

"selector": "A String", # Selects the methods to which this rule applies.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7921

#

7922

# Refer to selector for syntax details.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7923

"requested": [ # A list of full type names of requested contexts.

7924

"A String",

7925

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7926

"provided": [ # A list of full type names of provided contexts.

7927

"A String",

7928

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7929

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7930

# side channel from client to backend.

7931

"A String",

7932

],

7933

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7934

# side channel from backend to client.

7935

"A String",

7936

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7937

},

7938

],

7939

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7940

},

7941

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7942

"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>

7948

<pre>Retrieves the next page of results.

7949

7950

Args:

7951

previous_request: The request for the previous page. (required)

7952

previous_response: The response from the request for the previous page. (required)

7953

7954

Returns:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7955

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]

7956

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]

7961

<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]

7962

<pre>Creates a new service configuration (version) for a managed service based

7963

on

7964

user-supplied configuration source files (for example: OpenAPI

7965

Specification). This method stores the source configurations as well as the

7966

generated service configuration. To rollout the service configuration to

7967

other services,

7968

please call CreateServiceRollout.

7969

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7970

Only the 100 most recent configuration sources and ones referenced by

7971

existing service configurtions are kept for each service. The rest will be

7972

deleted eventually.

7973

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7974

Operation<response: SubmitConfigSourceResponse>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7975

7976

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7977

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]

7978

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

7979

body: object, The request body.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7980

The object takes the form of:

7981

7982

{ # Request message for SubmitConfigSource method.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

7983

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7984

# `google.api.Service` configuration based on the `ConfigSource` provided,

7985

# but the generated config and the sources will NOT be persisted.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7986

"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]

7987

# defined by `google.api.Service`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7988

"files": [ # Set of source configuration files that are used to generate a service

7989

# configuration (`google.api.Service`).

7990

{ # Generic specification of a source configuration file

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7991

"fileType": "A String", # The type of configuration file this represents.

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7992

"filePath": "A String", # The file name of the configuration file (full or relative path).

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

7993

"fileContents": "A String", # The bytes that constitute the file.

7994

},

7995

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

7996

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7997

# by the client for tracking purpose. If empty, the server may choose to

7998

# generate one instead.

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:

8009

8010

{ # This resource represents a long-running operation that is the result of a

8011

# network API call.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

8012

"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.

8013

# different programming environments, including REST APIs and RPC APIs. It is

8014

# used by [gRPC](https://github.com/grpc). Each `Status` message contains

8015

# three pieces of data: error code, error message, and error details.

8016

#

8017

# You can find out more about this error model and how to work with it in the

8018

# [API Design Guide](https://cloud.google.com/apis/design/errors).

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

8019

"details": [ # A list of messages that carry the error details. There is a common set of

8020

# message types for APIs to use.

8021

{

8022

"a_key": "", # Properties of the object. Contains field @type with type URL.

8023

},

8024

],

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

8025

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

8026

"message": "A String", # A developer-facing error message, which should be in English. Any

8027

# user-facing error message should be localized and sent in the

8028

# google.rpc.Status.details field, or localized by the client.

Bu Sun Kim

2020-05-27 12:20:54 -0700

[diff] [blame]

8029

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

8030

"metadata": { # Service-specific metadata associated with the operation. It typically

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

8031

# contains progress information and common metadata such as create time.

8032

# Some services might not provide such metadata. Any method that returns a

8033

# long-running operation should document the metadata type, if any.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

8034

"a_key": "", # Properties of the object. Contains field @type with type URL.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

8035

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

8036

"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]

8037

# If `true`, the operation is completed, and either `error` or `response` is

8038

# available.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

8039

"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]

8040

# method returns no data on success, such as `Delete`, the response is

8041

# `google.protobuf.Empty`. If the original method is standard

8042

# `Get`/`Create`/`Update`, the response should be the resource. For other

8043

# methods, the response should have the type `XxxResponse`, where `Xxx`

8044

# is the original method name. For example, if the original method name

8045

# is `TakeSnapshot()`, the inferred response type is

8046

# `TakeSnapshotResponse`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

8047

"a_key": "", # Properties of the object. Contains field @type with type URL.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

8048

},

Bu Sun Kim

2020-07-22 17:02:09 -0700

[diff] [blame^]

8049

"name": "A String", # The server-assigned name, which is only unique within the same service that

8050

# originally returns it. If you use the default HTTP mapping, the

8051

# `name` should be a resource name ending with `operations/{unique_id}`.

Jon Wayne Parrott