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

Thomas Coffee

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

[diff] [blame]

81

<code><a href="#get">get(serviceName, configId, x__xgafv=None, view=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

Thomas Coffee

2017-03-27 10:39:26 -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:

Jon Wayne Parrott

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

[diff] [blame]

130

# - selector: "*"

131

# requirements:

132

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

133

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

134

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

135

# monitoring, etc.

136

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

137

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

138

},

139

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

140

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

141

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

142

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

143

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

144

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

145

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

146

#

147

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

148

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

149

# by the API.

Thomas Coffee

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

[diff] [blame]

150

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

151

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

152

# without any article or other determiners. For example,

153

# `"Google Cloud SQL Database"`.

Dan O'Meara

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

[diff] [blame^]

154

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

155

# be used in documentation.

Bu Sun Kim

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

[diff] [blame]

156

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

157

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

158

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

159

{ # A description of a label.

160

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

161

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

162

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

163

},

164

],

165

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

166

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

167

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

168

# The maximum length of this value is 256 characters.

Dan O'Meara

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

[diff] [blame^]

169

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

170

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

171

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

172

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

173

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

174

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

Jon Wayne Parrott

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

[diff] [blame]

175

},

176

],

177

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

178

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

179

#

180

# - name: library.googleapis.com/activity_history

181

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

182

# display_name: Activity

183

# labels:

184

# - key: /customer_id

185

# description: Identifier of a library customer

186

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

187

# Runtime requests that contain labels not specified here are

188

# considered invalid.

189

{ # A description of a label.

190

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

191

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

192

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

193

},

194

],

195

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

196

# the user interface and should be concise.

Jon Wayne Parrott

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

[diff] [blame]

197

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

198

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

199

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

200

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

Thomas Coffee

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

[diff] [blame]

201

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

202

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

203

},

204

],

Thomas Coffee

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

[diff] [blame]

205

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

206

#

207

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

208

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

209

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

210

# change the names of the system parameters.

211

"rules": [ # Define system parameters.

212

#

213

# The parameters defined here will override the default parameters

214

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

215

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

216

# and names is implementation-dependent.

217

#

218

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

226

#

227

#

228

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

233

# parameters:

234

# - name: api_key

235

# http_header: Api-Key1

236

# - name: api_key

237

# http_header: Api-Key2

238

#

239

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

240

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

241

# methods.

242

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

243

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

244

# names are used the behavior is implementation-dependent.

245

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

246

# parameter-dependent.

247

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

248

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

249

# is implementation-dependent.

250

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

251

# sensitive.

252

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

253

# insensitive.

254

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

255

},

256

],

257

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

258

# methods in all APIs.

259

#

260

# Refer to selector for syntax details.

261

},

262

],

263

},

Jon Wayne Parrott

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

[diff] [blame]

264

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

265

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

266

#

267

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

268

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

Dan O'Meara

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

[diff] [blame^]

269

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

270

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

271

# to the backend.

272

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

273

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

274

#

275

# 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

285

# to "h2" for improved performance.

286

#

287

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

288

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

289

#

290

# See

291

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

292

# for more details on the supported values.

Bu Sun Kim

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

[diff] [blame]

293

"pathTranslation": "A String",

294

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

295

# value lower than this will be rejected.

Jon Wayne Parrott

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

[diff] [blame]

296

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

297

#

298

# Refer to selector for syntax details.

Bu Sun Kim

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

[diff] [blame]

299

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

300

# operation. The default is no deadline.

Dan O'Meara

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

[diff] [blame^]

301

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

302

# varies based on the request protocol and deployment environment.

303

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

304

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

305

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

306

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

Jon Wayne Parrott

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

[diff] [blame]

307

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

Dan O'Meara

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

[diff] [blame^]

308

#

309

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

310

# The following schemes are accepted:

311

#

312

# 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

319

# may cause constrasting behaviors across platforms.

320

#

321

# If the port is unspecified, the default is:

322

# - 80 for schemes without TLS

323

# - 443 for schemes with TLS

324

#

325

# For HTTP backends, use protocol

326

# to specify the protocol version.

327

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

328

#

329

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

330

#

331

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

332

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

333

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

334

# method.

335

#

336

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

337

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

338

#

339

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

340

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

341

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

342

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

343

# (selector) wins.

344

#

345

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

346

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

347

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

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

353

# rename_to: google.example.library.*

354

#

355

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

356

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

357

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

358

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

359

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

Jon Wayne Parrott

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

[diff] [blame]

360

},

361

],

362

},

Sai Cheemalapati

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

[diff] [blame]

363

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

Jon Wayne Parrott

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

[diff] [blame]

364

#

365

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

366

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

367

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

368

# to both producer and consumer projects, whereas the

369

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

370

# consumer project.

371

#

372

# monitored_resources:

373

# - type: library.googleapis.com/branch

374

# labels:

375

# - key: /city

376

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

377

# - key: /name

378

# description: The name of the branch.

379

# metrics:

380

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

385

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

390

# monitoring:

391

# producer_destinations:

392

# - monitored_resource: library.googleapis.com/branch

393

# metrics:

394

# - library.googleapis.com/book/returned_count

395

# consumer_destinations:

396

# - monitored_resource: library.googleapis.com/branch

397

# metrics:

398

# - library.googleapis.com/book/returned_count

399

# - library.googleapis.com/book/overdue_count

400

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

Bu Sun Kim

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

[diff] [blame]

401

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

402

# appear in multiple monitoring destinations if different aggregations are

403

# needed for different sets of metrics associated with that monitored

404

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

405

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

406

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

407

# or the consumer project).

408

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

409

# Service.monitored_resources section.

Bu Sun Kim

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

[diff] [blame]

410

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

411

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

Jon Wayne Parrott

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

[diff] [blame]

"A String",

],

},

],

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

Bu Sun Kim

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

[diff] [blame]

417

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

418

# appear in multiple monitoring destinations if different aggregations are

419

# needed for different sets of metrics associated with that monitored

420

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

421

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

422

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

423

# or the consumer project).

424

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

425

# Service.monitored_resources section.

Bu Sun Kim

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

[diff] [blame]

426

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

427

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

"A String",

],

},

],

},

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

434

#

435

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

436

# for billing:

437

#

438

# monitored_resources:

439

# - type: library.googleapis.com/branch

440

# labels:

441

# - key: /city

442

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

443

# - key: /name

444

# description: The name of the branch.

445

# metrics:

446

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

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

451

# - monitored_resource: library.googleapis.com/branch

452

# metrics:

453

# - library.googleapis.com/book/borrowed_count

454

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

455

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

456

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

457

# one consumer destination.

458

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

459

# bill against consumer project).

Bu Sun Kim

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

[diff] [blame]

460

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

Jon Wayne Parrott

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

[diff] [blame]

461

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

462

"A String",

463

],

Dan O'Meara

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

[diff] [blame^]

464

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

465

# Service.monitored_resources section.

Jon Wayne Parrott

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

[diff] [blame]

466

},

467

],

468

},

Bu Sun Kim

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

[diff] [blame]

469

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

Dan O'Meara

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

[diff] [blame^]

470

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

471

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

472

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

473

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

Jon Wayne Parrott

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

[diff] [blame]

474

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

475

#

476

# Example for an API targeted for external use:

477

#

478

# name: calendar.googleapis.com

479

# authentication:

Jon Wayne Parrott

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

[diff] [blame]

480

# providers:

481

# - id: google_calendar_auth

482

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

483

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

Jon Wayne Parrott

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

[diff] [blame]

484

# rules:

485

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame]

486

# requirements:

487

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

488

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

489

#

490

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

491

{ # Authentication rules for the service.

492

#

493

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

494

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

495

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

496

# request.

497

#

498

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

499

# ignored.

500

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

501

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

502

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

503

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

504

#

505

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

506

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

507

#

508

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

509

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

510

# the OAuth scope across all of those APIs.

511

#

512

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

513

# management about how developers will use them in practice.

514

#

515

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

516

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

517

# due to the backend requiring additional scopes or permissions.

518

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

519

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

#

# Example:

#

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

524

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

525

},

526

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

527

{ # User-defined authentication requirements, including support for

Bu Sun Kim

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

[diff] [blame]

528

# [JSON Web Token

529

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

Jon Wayne Parrott

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

[diff] [blame]

530

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame]

535

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

536

# implemented and accepted in all the runtime components.

537

#

538

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

539

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

540

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

541

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

542

# "https://Service_name/API_name"

543

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

544

# LibraryService API will only accept JWTs with the following audience

545

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

550

# bookstore_web.apps.googleusercontent.com

551

},

552

],

Dan O'Meara

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

[diff] [blame^]

553

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

Jon Wayne Parrott

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

[diff] [blame]

554

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

555

#

556

# Refer to selector for syntax details.

557

},

558

],

559

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

Bu Sun Kim

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

[diff] [blame]

560

{ # Configuration for an authentication provider, including support for

561

# [JSON Web Token

562

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

Dan O'Meara

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

[diff] [blame^]

563

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

564

#

565

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

566

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

567

# all headers first, then URL query parameters.

568

#

569

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

570

# 1) Authorization: Bearer

571

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

572

# 3) access_token query parameter

573

#

574

# Default locations can be specified as followings:

575

# jwt_locations:

576

# - header: Authorization

577

# value_prefix: "Bearer "

578

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

579

# - query: access_token

580

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

581

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

582

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

583

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

584

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

585

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

586

# extracted after the prefix is removed.

587

#

588

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

589

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

590

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

591

},

592

],

593

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

594

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

595

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

596

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

597

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

598

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

599

# will be accepted.

600

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

601

# accept JWTs with the following audiences:

602

# -

603

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

604

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

609

# bookstore_web.apps.googleusercontent.com

Bu Sun Kim

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

[diff] [blame]

610

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

611

# [OpenID

612

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

613

# Optional if the key set document:

614

# - can be retrieved from

615

# [OpenID

616

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

617

# the issuer.

618

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

619

# service account).

620

#

621

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

Jon Wayne Parrott

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

[diff] [blame]

622

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

623

# `AuthRequirement.provider_id`.

624

#

625

# Example: "bookstore_auth".

Bu Sun Kim

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

[diff] [blame]

626

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

627

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

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

[diff] [blame]

628

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

629

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

630

# Usually a URL or an email address.

631

#

632

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

633

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

},

],

},

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

638

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

639

#

640

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

641

{ # Usage configuration rules for the service.

642

#

643

# NOTE: Under development.

644

#

645

#

646

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

647

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

648

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

649

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

650

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

651

# allow/disallow unregistered calls.

652

#

653

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

659

#

660

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

#

# usage:

# rules:

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

665

# allow_unregistered_calls: true

Dan O'Meara

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

[diff] [blame^]

666

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

667

# methods in all APIs.

668

#

669

# Refer to selector for syntax details.

Bu Sun Kim

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

[diff] [blame]

670

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

671

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

672

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

673

# methods, such as service health check methods.

674

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

675

# that don't identify any user or application.

Jon Wayne Parrott

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

[diff] [blame]

676

},

677

],

Dan O'Meara

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

[diff] [blame^]

678

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

679

#

680

#

681

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

682

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

687

# display_name: "Cloud XXX Service Agent"

688

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

689

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

690

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

691

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

692

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

693

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

694

#

695

# An example name would be:

696

# `projects/123456789`

697

},

Jon Wayne Parrott

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

[diff] [blame]

698

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

699

# service producer.

700

#

701

# Google Service Management currently only supports

702

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

703

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

704

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

705

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

Jon Wayne Parrott

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

[diff] [blame]

706

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

Dan O'Meara

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

[diff] [blame^]

707

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

Jon Wayne Parrott

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

[diff] [blame]

708

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

709

"A String",

710

],

711

},

Bu Sun Kim

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

[diff] [blame]

712

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

713

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

714

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

Dan O'Meara

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

[diff] [blame^]

715

#

Bu Sun Kim

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

[diff] [blame]

716

# The latest config version is `3`.

717

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

718

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

719

# HttpRule, each specifying the mapping of an RPC method

720

# to one or more HTTP REST API methods.

721

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

722

#

723

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

Bu Sun Kim

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

[diff] [blame]

724

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

725

#

Bu Sun Kim

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

[diff] [blame]

726

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

727

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

728

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

729

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

730

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

731

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

732

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

733

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

734

#

Bu Sun Kim

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

[diff] [blame]

735

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

736

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

737

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

738

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

739

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

740

#

741

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

742

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

743

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

744

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

745

# the URL path.

746

#

747

# Example:

Jon Wayne Parrott

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

[diff] [blame]

748

#

749

# service Messaging {

750

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

751

# option (google.api.http) = {

752

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

753

# };

Jon Wayne Parrott

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

[diff] [blame]

754

# }

755

# }

756

# message GetMessageRequest {

Bu Sun Kim

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

[diff] [blame]

757

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

Jon Wayne Parrott

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

[diff] [blame]

758

# }

759

# message Message {

Bu Sun Kim

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

[diff] [blame]

760

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

Jon Wayne Parrott

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

[diff] [blame]

761

# }

762

#

Bu Sun Kim

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

[diff] [blame]

763

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

Jon Wayne Parrott

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

[diff] [blame]

764

#

Bu Sun Kim

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

[diff] [blame]

765

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

766

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

Bu Sun Kim

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

[diff] [blame]

767

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

Jon Wayne Parrott

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

[diff] [blame]

768

#

Bu Sun Kim

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

[diff] [blame]

769

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

770

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

771

# For example:

Jon Wayne Parrott

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

[diff] [blame]

772

#

Sai Cheemalapati

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

[diff] [blame]

773

# service Messaging {

774

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame]

775

# option (google.api.http) = {

776

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

777

# };

Sai Cheemalapati

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

[diff] [blame]

778

# }

779

# }

Jon Wayne Parrott

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

[diff] [blame]

780

# message GetMessageRequest {

781

# message SubMessage {

782

# string subfield = 1;

783

# }

Bu Sun Kim

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

[diff] [blame]

784

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

785

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

786

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

Jon Wayne Parrott

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

[diff] [blame]

787

# }

788

#

Jon Wayne Parrott

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

[diff] [blame]

789

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

790

#

Bu Sun Kim

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

[diff] [blame]

791

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

792

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

Dan O'Meara

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

[diff] [blame^]

793

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

Bu Sun Kim

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

[diff] [blame]

794

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

795

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

796

#

Bu Sun Kim

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

[diff] [blame]

797

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

798

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

799

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

800

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

801

# message is mapped to a separate parameter, such as

Dan O'Meara

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

[diff] [blame^]

802

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

Jon Wayne Parrott

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

[diff] [blame]

803

#

Bu Sun Kim

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

[diff] [blame]

804

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

Jon Wayne Parrott

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

[diff] [blame]

805

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

806

# message resource collection:

807

#

Jon Wayne Parrott

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

[diff] [blame]

808

# service Messaging {

809

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

810

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

811

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

Jon Wayne Parrott

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

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

817

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

818

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

819

# }

820

#

Jon Wayne Parrott

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

[diff] [blame]

821

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

822

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

823

# protos JSON encoding:

824

#

Bu Sun Kim

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

[diff] [blame]

825

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

826

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

Bu Sun Kim

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

[diff] [blame]

827

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

828

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

Jon Wayne Parrott

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

[diff] [blame]

829

#

830

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

831

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

832

# request body. This enables the following alternative definition of

833

# the update method:

834

#

Jon Wayne Parrott

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

[diff] [blame]

835

# service Messaging {

836

# rpc UpdateMessage(Message) returns (Message) {

837

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame]

838

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

Jon Wayne Parrott

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

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

845

# string text = 2;

846

# }

847

#

Jon Wayne Parrott

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

[diff] [blame]

848

#

849

# The following HTTP JSON to RPC mapping is enabled:

850

#

Bu Sun Kim

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

[diff] [blame]

851

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

852

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

Bu Sun Kim

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

[diff] [blame]

853

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

854

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

Jon Wayne Parrott

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

[diff] [blame]

855

#

856

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

857

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

858

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

Jon Wayne Parrott

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

[diff] [blame]

859

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

860

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

861

#

862

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

863

# the `additional_bindings` option. Example:

864

#

Jon Wayne Parrott

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

[diff] [blame]

865

# service Messaging {

866

# rpc GetMessage(GetMessageRequest) returns (Message) {

867

# option (google.api.http) = {

868

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

869

# additional_bindings {

870

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

871

# }

872

# };

Jon Wayne Parrott

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

[diff] [blame]

873

# }

Jon Wayne Parrott

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

[diff] [blame]

874

# }

875

# message GetMessageRequest {

876

# string message_id = 1;

877

# string user_id = 2;

878

# }

879

#

Bu Sun Kim

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

[diff] [blame]

880

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

Jon Wayne Parrott

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

[diff] [blame]

881

#

Bu Sun Kim

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

[diff] [blame]

882

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

883

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

884

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

Bu Sun Kim

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

[diff] [blame]

885

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

886

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

887

#

Bu Sun Kim

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

[diff] [blame]

888

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

889

#

Bu Sun Kim

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

[diff] [blame]

890

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

891

# message) are classified into three categories:

892

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

893

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

894

# request body.

895

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

896

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

897

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

898

# name.

899

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

900

# are passed via URL path and HTTP request body.

901

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

902

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

Jon Wayne Parrott

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

[diff] [blame]

903

#

Bu Sun Kim

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

[diff] [blame]

904

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

905

#

906

# Template = "/" Segments [ Verb ] ;

907

# Segments = Segment { "/" Segment } ;

908

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

909

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

910

# FieldPath = IDENT { "." IDENT } ;

911

# Verb = ":" LITERAL ;

912

#

Bu Sun Kim

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

[diff] [blame]

913

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

914

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

915

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

916

#

Bu Sun Kim

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

[diff] [blame]

917

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

918

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

Jon Wayne Parrott

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

[diff] [blame]

919

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

920

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

921

#

Bu Sun Kim

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

[diff] [blame]

922

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

923

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

924

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

925

#

Bu Sun Kim

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

[diff] [blame]

926

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

927

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

928

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

929

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

930

# [Discovery

931

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

932

# `{var}`.

933

#

934

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

935

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

936

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

937

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

938

# unchanged. Such variables show up in the

939

# [Discovery

940

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

941

# `{+var}`.

942

#

943

# ## Using gRPC API Service Configuration

944

#

945

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

946

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

947

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

948

# proto message.

949

#

950

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

951

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

952

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

953

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

954

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

955

# specified in the service config will override any matching transcoding

956

# configuration in the proto.

#

# Example:

#

# http:

# rules:

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

963

# - selector: example.v1.Messaging.GetMessage

964

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

#

# ## Special notes

#

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

969

# proto to JSON conversion must follow the [proto3

970

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

971

#

972

# While the single segment variable follows the semantics of

973

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

974

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

975

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

976

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

977

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

978

# for multi segment variables.

979

#

980

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

981

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

982

#

983

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

984

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

985

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

986

#

987

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

988

# no client library can support such complicated mapping.

989

#

990

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

991

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

992

# Transcoding implementations may not support this feature.

993

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

994

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

995

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

Sai Cheemalapati

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

[diff] [blame]

996

#

Bu Sun Kim

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

[diff] [blame]

997

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

998

# message type.

Dan O'Meara

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

[diff] [blame^]

999

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

1000

# resources.

Jon Wayne Parrott

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

[diff] [blame]

1001

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

1002

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

1003

# the nesting may only be one level deep).

1004

# Object with schema name: HttpRule

1005

],

Dan O'Meara

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

[diff] [blame^]

1006

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

1007

#

1008

# Refer to selector for syntax details.

1009

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

1010

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

1011

# as the HTTP response body.

1012

#

1013

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

1014

# message type.

1015

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

1016

# half-duplex streaming method.

1017

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

Bu Sun Kim

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

[diff] [blame]

1018

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

Dan O'Meara

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

[diff] [blame^]

1019

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

Bu Sun Kim

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

[diff] [blame]

1020

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

1021

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

1022

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

1023

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

Thomas Coffee

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

[diff] [blame]

1024

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

1025

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

1026

},

Bu Sun Kim

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

[diff] [blame]

1027

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

Jon Wayne Parrott

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

[diff] [blame]

1028

},

1029

],

Bu Sun Kim

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

[diff] [blame]

1030

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

Sai Cheemalapati

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

[diff] [blame]

1031

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

1032

# left encoded.

1033

#

1034

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

1035

# segment matches.

Jon Wayne Parrott

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

[diff] [blame]

1036

},

1037

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

1038

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

1039

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

1040

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

1041

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

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

[diff] [blame]

1042

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

1043

#

1044

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

1045

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

1046

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

1047

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

1048

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

1049

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

1050

# detailed terminology.

Dan O'Meara

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

[diff] [blame^]

1051

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

1052

# followed by the interface's simple name.

Jon Wayne Parrott

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

[diff] [blame]

1053

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

1054

# message.

1055

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

1056

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

1057

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

1058

},

Bu Sun Kim

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

[diff] [blame]

1059

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

1060

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

1061

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

1062

# documentation and options are inherited as follows:

Jon Wayne Parrott

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

[diff] [blame]

1063

#

1064

# - If after comment and whitespace stripping, the documentation

1065

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

1066

# from the original method.

1067

#

1068

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

1069

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

1070

# inherited.

1071

#

1072

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

1073

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

Bu Sun Kim

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

[diff] [blame]

1074

# version of the including interface plus the root path if

1075

# specified.

Jon Wayne Parrott

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

[diff] [blame]

1076

#

1077

# Example of a simple mixin:

1078

#

1079

# package google.acl.v1;

1080

# service AccessControl {

1081

# // Get the underlying ACL object.

1082

# rpc GetAcl(GetAclRequest) returns (Acl) {

1083

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

# }

# }

#

# package google.storage.v2;

1088

# service Storage {

1089

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

1090

#

1091

# // Get a data record.

1092

# rpc GetData(GetDataRequest) returns (Data) {

1093

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

# }

# }

#

# Example of a mixin configuration:

1098

#

1099

# apis:

1100

# - name: google.storage.v2.Storage

1101

# mixins:

1102

# - name: google.acl.v1.AccessControl

1103

#

1104

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

1105

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

1106

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

1107

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

1108

# documentation and annotations as follows:

1109

#

1110

# service Storage {

1111

# // Get the underlying ACL object.

1112

# rpc GetAcl(GetAclRequest) returns (Acl) {

1113

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

# }

# ...

# }

#

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

1119

#

1120

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

1121

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

1122

#

1123

# apis:

1124

# - name: google.storage.v2.Storage

1125

# mixins:

1126

# - name: google.acl.v1.AccessControl

1127

# root: acls

1128

#

1129

# This implies the following inherited HTTP annotation:

1130

#

1131

# service Storage {

1132

# // Get the underlying ACL object.

1133

# rpc GetAcl(GetAclRequest) returns (Acl) {

1134

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

# }

# ...

# }

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

1139

# are rooted.

Bu Sun Kim

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

[diff] [blame]

1140

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

Jon Wayne Parrott

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

[diff] [blame]

1141

},

1142

],

1143

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

Bu Sun Kim

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

[diff] [blame]

1144

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

1145

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

1146

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

1147

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

1148

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

1149

# consistent with what is provided here.

Jon Wayne Parrott

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

[diff] [blame]

1150

#

1151

# The versioning schema uses [semantic

1152

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

1153

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

1154

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

1155

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

1156

# chosen based on the product plan.

1157

#

1158

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

Dan O'Meara

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

[diff] [blame^]

1159

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

Jon Wayne Parrott

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

[diff] [blame]

1160

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

1161

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

Bu Sun Kim

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

[diff] [blame]

1162

# experimental, non-GA interfaces.

1163

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

Jon Wayne Parrott

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

[diff] [blame]

1164

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

1165

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1166

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

1167

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

1168

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

1169

# `"google.api.http"`.

1170

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

1171

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

1172

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

1173

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1174

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

1175

},

1176

},

1177

],

Dan O'Meara

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

[diff] [blame^]

1178

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

1179

{ # Method represents a method of an API interface.

1180

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

1181

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

1182

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

1183

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

1184

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

1185

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

1186

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

1187

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

1188

# enumeration, etc.

1189

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

1190

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

1191

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

1192

# `"google.api.http"`.

1193

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

1194

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

1195

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

1196

# value using the google.protobuf.Int32Value type.

1197

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

},

},

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1203

},

1204

],

1205

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

1206

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1214

# - google.foo.v1.AnotherError

1215

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

1216

#

1217

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

1218

{ # A custom error rule.

1219

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

1220

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

1221

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

1222

#

1223

# Refer to selector for syntax details.

1224

},

1225

],

1226

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

1227

"A String",

1228

],

1229

},

Sai Cheemalapati

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

[diff] [blame]

1230

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

1231

# usage.

1232

#

Bu Sun Kim

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

[diff] [blame]

1233

# The metric based quota configuration works this way:

Sai Cheemalapati

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

[diff] [blame]

1234

# - The service configuration defines a set of metrics.

1235

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

1236

# corresponding costs.

1237

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

1238

# quota checks at runtime.

1239

#

1240

# An example quota configuration in yaml format:

1241

#

1242

# quota:

Bu Sun Kim

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

[diff] [blame]

1243

# limits:

Sai Cheemalapati

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

[diff] [blame]

1244

#

1245

# - name: apiWriteQpsPerProject

1246

# metric: library.googleapis.com/write_calls

1247

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

# values:

# STANDARD: 10000

#

#

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

1253

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

1254

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

1255

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1260

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

1261

# metric_costs:

1262

# library.googleapis.com/write_calls: 2

1263

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

1264

# metric_costs:

1265

# library.googleapis.com/write_calls: 1

1266

#

1267

# Corresponding Metric definition:

1268

#

1269

# metrics:

1270

# - name: library.googleapis.com/read_calls

1271

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1276

# display_name: Write requests

1277

# metric_kind: DELTA

1278

# value_type: INT64

Bu Sun Kim

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

[diff] [blame]

1279

#

Sai Cheemalapati

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

[diff] [blame]

1280

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

1281

# or more metrics.

1282

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

1283

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

1284

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

1285

# cost applied to each metric.

1286

#

1287

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

1288

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

1289

# The value must not be negative.

1290

"a_key": "A String",

1291

},

1292

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

1293

#

1294

# Refer to selector for syntax details.

1295

},

1296

],

1297

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

1298

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

1299

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

1300

# type combination defined within a `QuotaGroup`.

1301

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

1302

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

1303

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

1304

# display name generated from the configuration.

Dan O'Meara

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

[diff] [blame^]

1305

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

1306

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

1307

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

Sai Cheemalapati

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

[diff] [blame]

1308

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

1309

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

1310

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

1311

#

1312

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

1313

# are provisioning quota to selected consumers and blocking others.

1314

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

1315

# negative values are allowed.

1316

#

1317

# Used by group-based quotas only.

1318

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

1319

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

1320

# defined within the service config.

Bu Sun Kim

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

[diff] [blame]

1321

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

1322

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

1323

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

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

[diff] [blame]

1324

"a_key": "A String",

1325

},

1326

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

1327

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

1328

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

1329

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

1330

#

1331

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

1332

# indicating unlimited maximum quota.

1333

#

1334

# Used by group-based quotas only.

Dan O'Meara

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

[diff] [blame^]

1335

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

Sai Cheemalapati

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

[diff] [blame]

1336

#

1337

# Used by group-based quotas only.

1338

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

1339

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

1340

# billed amount when billing is enabled.

1341

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

1342

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

1343

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

1344

#

1345

# Used by group-based quotas only.

1346

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

1347

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

1348

# backend system.

1349

#

Sai Cheemalapati

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

[diff] [blame]

1350

# Here are some examples:

1351

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

1352

#

1353

# Note: the order of unit components is insignificant.

1354

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

Dan O'Meara

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

[diff] [blame^]

1355

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

1356

#

1357

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

1358

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

1359

#

1360

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

Jon Wayne Parrott

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

[diff] [blame]

},

],

},

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

Jon Wayne Parrott

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

[diff] [blame]

1365

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

1366

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

1367

# existing data unusable.

Jon Wayne Parrott

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

[diff] [blame]

1368

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

1369

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

Bu Sun Kim

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

[diff] [blame]

1370

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

1371

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

Dan O'Meara

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

[diff] [blame^]

1372

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

Jon Wayne Parrott

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

[diff] [blame]

1373

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

Sai Cheemalapati

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

[diff] [blame]

1374

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

Jon Wayne Parrott

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

[diff] [blame]

1375

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

Sai Cheemalapati

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

[diff] [blame]

1376

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

Jon Wayne Parrott

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

[diff] [blame]

1377

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

1378

# instance of this metric type. For example, the

1379

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

1380

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

1381

# you can look at latencies for successful responses or just

1382

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1383

{ # A description of a label.

1384

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

1385

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

1386

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

1387

},

1388

],

Bu Sun Kim

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

[diff] [blame]

1389

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

Dan O'Meara

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

[diff] [blame^]

1390

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

1391

# series, which is identified partially by

1392

# a metric type and a MonitoredResourceDescriptor, that is associated

1393

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

1394

# resource types listed here.

1395

"A String",

1396

],

1397

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

1398

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

1399

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

1400

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

1401

# data loss due to errors.

1402

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

1403

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

1404

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

1405

# a smaller sampling period.

1406

},

Jon Wayne Parrott

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

[diff] [blame]

1407

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

Bu Sun Kim

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

[diff] [blame]

1408

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

1409

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

1410

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1411

#

Jon Wayne Parrott

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

[diff] [blame]

1412

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

Bu Sun Kim

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

[diff] [blame]

1413

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

Jon Wayne Parrott

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

[diff] [blame]

1414

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

Dan O'Meara

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

[diff] [blame^]

1415

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

1416

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

1417

# defines the representation of the stored metric values.

1418

#

1419

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

1420

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

1421

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

1422

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

1423

# matter how it may be displayed..

1424

#

1425

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

1426

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

1427

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

1428

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

1429

#

1430

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

1431

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

1432

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

1433

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

1434

#

1435

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

Jon Wayne Parrott

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

[diff] [blame]

1436

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

1437

#

1438

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

1448

#

Dan O'Meara

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

[diff] [blame^]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

1456

# * `Y` yotta (10^24)

1457

#

1458

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

1459

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

1460

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

1461

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

1462

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

1463

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

1464

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

1465

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1472

#

1473

# **Grammar**

1474

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1475

# The grammar also includes these connectors:

1476

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1477

# * `/` division or ratio (as an infix operator). For examples,

1478

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

1479

# have `/s` in a metric `unit`; rates should always be computed at

1480

# query time from the underlying cumulative or delta value).

1481

# * `.` multiplication or composition (as an infix operator). For

1482

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1483

#

1484

# The grammar for a unit is as follows:

1485

#

1486

# Expression = Component { "." Component } { "/" Component } ;

1487

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1488

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

1494

#

1495

# Notes:

1496

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1497

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

1498

# is used alone, then the unit is equivalent to `1`. For examples,

1499

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1500

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1501

# containing `{` or `}`.

1502

# * `1` represents a unitary [dimensionless

1503

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

1504

# as in `1/s`. It is typically used when none of the basic units are

1505

# appropriate. For example, "new users per day" can be represented as

1506

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

1507

# users). Alternatively, "thousands of page views per day" would be

1508

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

1509

# value of `5.3` would mean "5300 page views per day").

1510

# * `%` represents dimensionless value of 1/100, and annotates values giving

1511

# a percentage (so the metric values are typically in the range of 0..100,

1512

# and a metric value `3` means "3 percent").

1513

# * `10^2.%` indicates a metric contains a ratio, typically in the range

1514

# 0..1, that will be multiplied by 100 and displayed as a percentage

1515

# (so a metric value `0.03` means "3 percent").

1516

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1517

},

1518

],

1519

"enums": [ # A list of all enum types included in this API service. Enums

1520

# referenced directly or indirectly by the `apis` are automatically

1521

# included. Enums which are not referenced but shall be included

1522

# should be listed here by name. Example:

1523

#

1524

# enums:

1525

# - name: google.someapi.v1.SomeEnum

1526

{ # Enum type definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1527

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1528

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1529

# protobuf element, like the file in which it is defined.

1530

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1531

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1532

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1533

"options": [ # Protocol buffer options.

1534

{ # A protocol buffer option, which can be attached to a message, field,

1535

# enumeration, etc.

1536

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1537

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1538

# For custom options, it should be the fully-qualified name. For example,

1539

# `"google.api.http"`.

1540

"value": { # The option's value packed in an Any message. If the value is a primitive,

1541

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1542

# should be used. If the value is an enum, it should be stored as an int32

1543

# value using the google.protobuf.Int32Value type.

1544

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1549

"enumvalue": [ # Enum value definitions.

1550

{ # Enum value definition.

1551

"options": [ # Protocol buffer options.

1552

{ # A protocol buffer option, which can be attached to a message, field,

1553

# enumeration, etc.

1554

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1555

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1556

# For custom options, it should be the fully-qualified name. For example,

1557

# `"google.api.http"`.

1558

"value": { # The option's value packed in an Any message. If the value is a primitive,

1559

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1560

# should be used. If the value is an enum, it should be stored as an int32

1561

# value using the google.protobuf.Int32Value type.

1562

"a_key": "", # Properties of the object. Contains field @type with type URL.

1563

},

1564

},

1565

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1566

"number": 42, # Enum value number.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1567

"name": "A String", # Enum value name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1568

},

1569

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1570

},

1571

],

1572

"types": [ # A list of all proto message types included in this API service.

1573

# Types referenced directly or indirectly by the `apis` are

1574

# automatically included. Messages which are not referenced but

1575

# shall be included, such as types used by the `google.protobuf.Any` type,

1576

# should be listed here by name. Example:

1577

#

1578

# types:

1579

# - name: google.protobuf.Int32

1580

{ # A protocol buffer message type.

1581

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1582

"A String",

1583

],

1584

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1585

"fields": [ # The list of fields.

1586

{ # A single field of a message type.

1587

"kind": "A String", # The field type.

1588

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1589

# types. The first type has index 1; zero means the type is not in the list.

1590

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1591

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1592

"name": "A String", # The field name.

1593

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1594

"jsonName": "A String", # The field JSON name.

1595

"number": 42, # The field number.

1596

"cardinality": "A String", # The field cardinality.

1597

"options": [ # The protocol buffer options.

1598

{ # A protocol buffer option, which can be attached to a message, field,

1599

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1600

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1601

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1602

# For custom options, it should be the fully-qualified name. For example,

1603

# `"google.api.http"`.

1604

"value": { # The option's value packed in an Any message. If the value is a primitive,

1605

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1606

# should be used. If the value is an enum, it should be stored as an int32

1607

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1608

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1613

},

1614

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1615

"syntax": "A String", # The source syntax.

1616

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1617

# protobuf element, like the file in which it is defined.

1618

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1619

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1620

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1621

"options": [ # The protocol buffer options.

1622

{ # A protocol buffer option, which can be attached to a message, field,

1623

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1624

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1625

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1626

# For custom options, it should be the fully-qualified name. For example,

1627

# `"google.api.http"`.

1628

"value": { # The option's value packed in an Any message. If the value is a primitive,

1629

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1630

# should be used. If the value is an enum, it should be stored as an int32

1631

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1632

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1638

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1639

#

1640

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1641

# producer and consumer projects. In the example, the `activity_history`

1642

# log is sent to both the producer and consumer projects, whereas the

1643

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1644

#

1645

# monitored_resources:

1646

# - type: library.googleapis.com/branch

1647

# labels:

1648

# - key: /city

1649

# description: The city where the library branch is located in.

1650

# - key: /name

1651

# description: The name of the branch.

1652

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1653

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1654

# labels:

1655

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1656

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1657

# logging:

1658

# producer_destinations:

1659

# - monitored_resource: library.googleapis.com/branch

1660

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1661

# - activity_history

1662

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1663

# consumer_destinations:

1664

# - monitored_resource: library.googleapis.com/branch

1665

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1666

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1667

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

1668

# There can be multiple producer destinations, each one must have a

1669

# different monitored resource type. A log can be used in at most

1670

# one producer destination.

1671

{ # Configuration of a specific logging destination (the producer project

1672

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1673

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1674

# Service.monitored_resources section.

1675

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1676

# be defined in the Service.logs section. If the log name is

1677

# not a domain scoped name, it will be automatically prefixed with

1678

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

1684

# There can be multiple consumer destinations, each one must have a

1685

# different monitored resource type. A log can be used in at most

1686

# one consumer destination.

1687

{ # Configuration of a specific logging destination (the producer project

1688

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1689

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1690

# Service.monitored_resources section.

1691

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1692

# be defined in the Service.logs section. If the log name is

1693

# not a domain scoped name, it will be automatically prefixed with

1694

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1700

"name": "A String", # The service name, which is a DNS-like logical identifier for the

1701

# service, such as `calendar.googleapis.com`. The service name

1702

# typically goes through DNS verification to make sure the owner

1703

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1704

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

1705

#

1706

# Example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1707

# <pre><code>documentation:

1708

# summary: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1709

# The Google Calendar API gives access

1710

# to most calendar features.

1711

# pages:

1712

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1713

# content: &#40;== include google/foo/overview.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1714

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1715

# content: &#40;== include google/foo/tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1716

# subpages;

1717

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1718

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1719

# rules:

1720

# - selector: google.calendar.Calendar.Get

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1721

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1722

# ...

1723

# - selector: google.calendar.Calendar.Put

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1724

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1725

# ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1726

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1727

# Documentation is provided in markdown syntax. In addition to

1728

# standard markdown features, definition lists, tables and fenced

1729

# code blocks are supported. Section headers can be provided and are

1730

# interpreted relative to the section nesting of the context where

1731

# a documentation fragment is embedded.

1732

#

1733

# Documentation from the IDL is merged with documentation defined

1734

# via the config at normalization time, where documentation provided

1735

# by config rules overrides IDL provided.

1736

#

1737

# A number of constructs specific to the API platform are supported

1738

# in documentation text.

1739

#

1740

# In order to reference a proto element, the following

1741

# notation can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1742

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1743

# To override the display text used for the link, this can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1744

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1745

# Text can be excluded from doc using the following notation:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1746

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1747

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1748

# A few directives are available in documentation. Note that

1749

# directives must appear on a single line to be properly

1750

# identified. The `include` directive includes a markdown file from

1751

# an external source:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1752

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1753

# The `resource_for` directive marks a message to be the resource of

1754

# a collection in REST view. If it is not specified, tools attempt

1755

# to infer the resource from the operations in a collection:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1756

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1757

# The directive `suppress_warning` does not directly affect documentation

1758

# and is documented together with service config validation.

1759

"rules": [ # A list of documentation rules that apply to individual API elements.

1760

#

1761

# **NOTE:** All service configuration rules follow "last one wins" order.

1762

{ # A documentation rule provides information about individual API elements.

1763

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1764

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

1765

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1766

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

1767

# qualified name of the element which may end in "*", indicating a wildcard.

1768

# Wildcards are only allowed at the end and for a whole component of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1769

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

1770

# wildcard will match one or more components. To specify a default for all

1771

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1772

},

1773

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1774

"documentationRootUrl": "A String", # The URL to the root of documentation.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1775

"summary": "A String", # A short summary of what the service does. Can only be provided by

1776

# plain text.

1777

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

1778

# from the yaml file) is not suitable. This can be seen in any fully

1779

# specified service urls as well as sections that show a base that other

1780

# urls are relative to.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1781

"overview": "A String", # Declares a single overview page. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1782

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1783

# summary: ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1784

# overview: &#40;== include overview.md ==&#41;

1785

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1786

# This is a shortcut for the following declaration (using pages style):

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1787

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1788

# summary: ...

1789

# pages:

1790

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1791

# content: &#40;== include overview.md ==&#41;

1792

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1793

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1794

"pages": [ # The top level pages for the documentation set.

1795

{ # Represents a documentation page. A page can contain subpages to represent

1796

# nested documentation set structure.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1797

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

1798

# ==&#41;</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1799

"subpages": [ # Subpages of this page. The order of subpages specified here will be

1800

# honored in the generated docset.

1801

# Object with schema name: Page

1802

],

1803

"name": "A String", # The name of the page. It will be used as an identity of the page to

1804

# generate URI of the page, text of the link to this page in navigation,

1805

# etc. The full page name (start from the root page name to this page

1806

# concatenated with `.`) can be used as reference to the page in your

1807

# documentation. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1808

# <pre><code>pages:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1809

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1810

# content: &#40;== include tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1811

# subpages:

1812

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1813

# content: &#40;== include tutorial_java.md ==&#41;

1814

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1815

# You can reference `Java` page using Markdown reference link syntax:

1816

# `Java`.

1817

},

1818

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1819

},

1820

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

1821

"sourceFiles": [ # All files used during config generation.

1822

{

1823

"a_key": "", # Properties of the object. Contains field @type with type URL.

1824

},

1825

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1826

},

1827

"systemTypes": [ # A list of all proto message types included in this API service.

1828

# It serves similar purpose as [google.api.Service.types], except that

1829

# these types are not needed by user-defined APIs. Therefore, they will not

1830

# show up in the generated discovery doc. This field should only be used

1831

# to define system APIs in ESF.

1832

{ # A protocol buffer message type.

1833

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1834

"A String",

1835

],

1836

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1837

"fields": [ # The list of fields.

1838

{ # A single field of a message type.

1839

"kind": "A String", # The field type.

1840

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1841

# types. The first type has index 1; zero means the type is not in the list.

1842

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1843

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1844

"name": "A String", # The field name.

1845

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1846

"jsonName": "A String", # The field JSON name.

1847

"number": 42, # The field number.

1848

"cardinality": "A String", # The field cardinality.

1849

"options": [ # The protocol buffer options.

1850

{ # A protocol buffer option, which can be attached to a message, field,

1851

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1852

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1853

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1854

# For custom options, it should be the fully-qualified name. For example,

1855

# `"google.api.http"`.

1856

"value": { # The option's value packed in an Any message. If the value is a primitive,

1857

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1858

# should be used. If the value is an enum, it should be stored as an int32

1859

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1860

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1865

},

1866

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1867

"syntax": "A String", # The source syntax.

1868

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1869

# protobuf element, like the file in which it is defined.

1870

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1871

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1872

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1873

"options": [ # The protocol buffer options.

1874

{ # A protocol buffer option, which can be attached to a message, field,

1875

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1876

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1877

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1878

# For custom options, it should be the fully-qualified name. For example,

1879

# `"google.api.http"`.

1880

"value": { # The option's value packed in an Any message. If the value is a primitive,

1881

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1882

# should be used. If the value is an enum, it should be stored as an int32

1883

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1884

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

1899

# - google.rpc.context.OriginContext

1900

#

1901

# The above specifies that all methods in the API request

1902

# `google.rpc.context.ProjectContext` and

1903

# `google.rpc.context.OriginContext`.

1904

#

1905

# Available context types are defined in package

1906

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1907

#

1908

# This also provides mechanism to whitelist any protobuf message extension that

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1909

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

1910

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1911

# 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"

1919

# allowed_request_extensions:

1920

# - google.foo.v1.NewExtension

1921

# allowed_response_extensions:

1922

# - google.foo.v1.NewExtension

1923

#

1924

# You can also specify extension ID instead of fully qualified extension name

1925

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1926

"rules": [ # A list of RPC context rules that apply to individual API methods.

1927

#

1928

# **NOTE:** All service configuration rules follow "last one wins" order.

1929

{ # A context rule provides information about the context for an individual API

1930

# element.

1931

"provided": [ # A list of full type names of provided contexts.

1932

"A String",

1933

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1934

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1935

# side channel from backend to client.

1936

"A String",

1937

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1938

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1939

# side channel from client to backend.

1940

"A String",

1941

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1942

"requested": [ # A list of full type names of requested contexts.

1943

"A String",

1944

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

1945

"selector": "A String", # Selects the methods to which this rule applies.

1946

#

1947

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1948

},

1949

],

1950

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1951

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

1952

# with the same name as the service is automatically generated to service all

1953

# defined APIs.

1954

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

1955

# A service may expose any number of endpoints, and all endpoints share the

1956

# same service configuration, such as quota configuration and monitoring

1957

# configuration.

1958

#

1959

# Example service configuration:

1960

#

1961

# name: library-example.googleapis.com

1962

# endpoints:

1963

# # Below entry makes 'google.example.library.v1.Library'

1964

# # API be served from endpoint address library-example.googleapis.com.

1965

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

1966

# # it to decide whether the subsequent cross-origin request is

1967

# # allowed to proceed.

1968

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1969

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1970

"allowCors": True or False, # Allowing

1971

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

1972

# cross-domain traffic, would allow the backends served from this endpoint to

1973

# receive and respond to HTTP OPTIONS requests. The response will be used by

1974

# the browser to determine whether the subsequent cross-origin request is

1975

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1976

"target": "A String", # The specification of an Internet routable address of API frontend that will

1977

# handle requests to this [API

1978

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

1979

# either a valid IPv4 address or a fully-qualified domain name. For example,

1980

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1981

"features": [ # The list of features enabled on this endpoint.

1982

"A String",

1983

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1984

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1985

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1986

# please specify multiple google.api.Endpoint for each of the intended

1987

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1988

#

1989

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1994

}

1995

1996

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2003

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2004

{ # `Service` is the root object of Google service configuration schema. It

2005

# describes basic information about a service, such as the name and the

2006

# title, and delegates other aspects to sub-sections. Each sub-section is

2007

# either a proto message or a repeated proto message that configures a

2008

# 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]

2013

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2014

# name: calendar.googleapis.com

2015

# title: Google Calendar API

2016

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2017

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2018

# authentication:

2019

# providers:

2020

# - id: google_calendar_auth

2021

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2022

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2023

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2024

# - selector: "*"

2025

# requirements:

2026

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2027

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2028

# service controller handles features like abuse, quota, billing, logging,

2029

# monitoring, etc.

2030

"environment": "A String", # The service control environment to use. If empty, no control plane

2031

# feature (like quota and billing) will be enabled.

2032

},

2033

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

2034

# by the Service.monitoring and Service.logging configurations.

2035

{ # An object that describes the schema of a MonitoredResource object using a

2036

# type name and a set of labels. For example, the monitored resource

2037

# descriptor for Google Compute Engine VM instances has a type of

2038

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

2039

# `"zone"` to identify particular VM instances.

2040

#

2041

# Different APIs can support different monitored resource types. APIs generally

2042

# provide a `list` method that returns the monitored resource descriptors used

2043

# by the API.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2044

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

2045

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

2046

# without any article or other determiners. For example,

2047

# `"Google Cloud SQL Database"`.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2048

"description": "A String", # Optional. A detailed description of the monitored resource type that might

2049

# be used in documentation.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2050

"labels": [ # Required. A set of labels used to describe instances of this monitored

2051

# resource type. For example, an individual Google Cloud SQL database is

2052

# identified by values for the labels `"database_id"` and `"zone"`.

2053

{ # A description of a label.

2054

"valueType": "A String", # The type of data that can be assigned to the label.

2055

"description": "A String", # A human-readable description for the label.

2056

"key": "A String", # The label key.

2057

},

2058

],

2059

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

2060

"type": "A String", # Required. The monitored resource type. For example, the type

2061

# `"cloudsql_database"` represents databases in Google Cloud SQL.

2062

# The maximum length of this value is 256 characters.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2063

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

2064

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

2065

# {type} is the value of the `type` field in this object and

2066

# {project_id} is a project ID that provides API-specific context for

2067

# accessing the type. APIs that do not use project information can use the

2068

# resource name format `"monitoredResourceDescriptors/{type}"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2069

},

2070

],

2071

"logs": [ # Defines the logs used by this service.

2072

{ # A description of a log type. Example in YAML format:

2073

#

2074

# - name: library.googleapis.com/activity_history

2075

# description: The history of borrowing and returning library items.

2076

# display_name: Activity

2077

# labels:

2078

# - key: /customer_id

2079

# description: Identifier of a library customer

2080

"labels": [ # The set of labels that are available to describe a specific log entry.

2081

# Runtime requests that contain labels not specified here are

2082

# considered invalid.

2083

{ # A description of a label.

2084

"valueType": "A String", # The type of data that can be assigned to the label.

2085

"description": "A String", # A human-readable description for the label.

2086

"key": "A String", # The label key.

2087

},

2088

],

2089

"displayName": "A String", # The human-readable name for this log. This information appears on

2090

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2091

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2092

# include the following characters: upper- and lower-case alphanumeric

2093

# characters [A-Za-z0-9], and punctuation characters including

2094

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2095

"description": "A String", # A human-readable description of this log. This information appears in

2096

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2097

},

2098

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2099

"systemParameters": { # ### System parameter configuration # System parameter configuration.

2100

#

2101

# A system parameter is a special kind of parameter defined by the API

2102

# system, not by an individual API. It is typically mapped to an HTTP header

2103

# and/or a URL query parameter. This configuration specifies which methods

2104

# change the names of the system parameters.

2105

"rules": [ # Define system parameters.

2106

#

2107

# The parameters defined here will override the default parameters

2108

# implemented by the system. If this field is missing from the service

2109

# config, default system parameters will be used. Default system parameters

2110

# and names is implementation-dependent.

2111

#

2112

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

2120

#

2121

#

2122

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

2127

# parameters:

2128

# - name: api_key

2129

# http_header: Api-Key1

2130

# - name: api_key

2131

# http_header: Api-Key2

2132

#

2133

# **NOTE:** All service configuration rules follow "last one wins" order.

2134

{ # Define a system parameter rule mapping system parameter definitions to

2135

# methods.

2136

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

2137

# For a given method call, only one of them should be used. If multiple

2138

# names are used the behavior is implementation-dependent.

2139

# If none of the specified names are present the behavior is

2140

# parameter-dependent.

2141

{ # Define a parameter's name and location. The parameter may be passed as either

2142

# an HTTP header or a URL query parameter, and if both are passed the behavior

2143

# is implementation-dependent.

2144

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

2145

# sensitive.

2146

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

2147

# insensitive.

2148

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

2149

},

2150

],

2151

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2152

# methods in all APIs.

2153

#

2154

# Refer to selector for syntax details.

2155

},

2156

],

2157

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2158

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

2159

"rules": [ # A list of API backend rules that apply to individual API methods.

2160

#

2161

# **NOTE:** All service configuration rules follow "last one wins" order.

2162

{ # A backend rule provides configuration for an individual API element.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2163

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

2164

# This ID token will be added in the HTTP "authorization" header, and sent

2165

# to the backend.

2166

"protocol": "A String", # The protocol used for sending a request to the backend.

2167

# The supported values are "http/1.1" and "h2".

2168

#

2169

# 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

2179

# to "h2" for improved performance.

2180

#

2181

# Configuring this field to non-default values is only supported for secure

2182

# HTTP backends. This field will be ignored for all other backends.

2183

#

2184

# See

2185

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

2186

# for more details on the supported values.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2187

"pathTranslation": "A String",

2188

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

2189

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2190

"selector": "A String", # Selects the methods to which this rule applies.

2191

#

2192

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2193

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

2194

# operation. The default is no deadline.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2195

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

2196

# varies based on the request protocol and deployment environment.

2197

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

2198

# original "Authorization" HTTP header will be preserved. If the header is

2199

# used to carry the original token and is expected by the backend, this

2200

# field must be set to true to preserve the header.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2201

"address": "A String", # The address of the API backend.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2202

#

2203

# The scheme is used to determine the backend protocol and security.

2204

# The following schemes are accepted:

2205

#

2206

# 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

2213

# may cause constrasting behaviors across platforms.

2214

#

2215

# If the port is unspecified, the default is:

2216

# - 80 for schemes without TLS

2217

# - 443 for schemes with TLS

2218

#

2219

# For HTTP backends, use protocol

2220

# to specify the protocol version.

2221

"renameTo": "A String", # Unimplemented. Do not use.

2222

#

2223

# The new name the selected proto elements should be renamed to.

2224

#

2225

# The package, the service and the method can all be renamed.

2226

# The backend server should implement the renamed proto. However, clients

2227

# should call the original method, and ESF routes the traffic to the renamed

2228

# method.

2229

#

2230

# HTTP clients should call the URL mapped to the original method.

2231

# gRPC and Stubby clients should call the original method with package name.

2232

#

2233

# For legacy reasons, ESF allows Stubby clients to call with the

2234

# short name (without the package name). However, for API Versioning(or

2235

# multiple methods mapped to the same short name), all Stubby clients must

2236

# call the method's full name with the package name, otherwise the first one

2237

# (selector) wins.

2238

#

2239

# If this `rename_to` is specified with a trailing `*`, the `selector` must

2240

# be specified with a trailing `*` as well. The all element short names

2241

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

2247

# rename_to: google.example.library.*

2248

#

2249

# The selector matches `google.example.library.v1.Library.CreateShelf` and

2250

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

2251

# `google.example.library.Library.CreateShelf` and

2252

# `google.example.library.Library.CreateBook`. It essentially renames the

2253

# proto package name section of the matched proto service and methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2254

},

2255

],

2256

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2257

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2258

#

2259

# The example below shows how to configure monitored resources and metrics

2260

# for monitoring. In the example, a monitored resource and two metrics are

2261

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2262

# to both producer and consumer projects, whereas the

2263

# `library.googleapis.com/book/overdue_count` metric is only sent to the

2264

# consumer project.

2265

#

2266

# monitored_resources:

2267

# - type: library.googleapis.com/branch

2268

# labels:

2269

# - key: /city

2270

# description: The city where the library branch is located in.

2271

# - key: /name

2272

# description: The name of the branch.

2273

# metrics:

2274

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2279

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2284

# monitoring:

2285

# producer_destinations:

2286

# - monitored_resource: library.googleapis.com/branch

2287

# metrics:

2288

# - library.googleapis.com/book/returned_count

2289

# consumer_destinations:

2290

# - monitored_resource: library.googleapis.com/branch

2291

# metrics:

2292

# - library.googleapis.com/book/returned_count

2293

# - library.googleapis.com/book/overdue_count

2294

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2295

# There can be multiple producer destinations. A monitored resouce type may

2296

# appear in multiple monitoring destinations if different aggregations are

2297

# needed for different sets of metrics associated with that monitored

2298

# resource type. A monitored resource and metric pair may only be used once

2299

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2300

{ # Configuration of a specific monitoring destination (the producer project

2301

# or the consumer project).

2302

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2303

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2304

"metrics": [ # Types of the metrics to report to this monitoring destination.

2305

# Each type must be defined in Service.metrics section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2311

# There can be multiple consumer destinations. A monitored resouce type may

2312

# appear in multiple monitoring destinations if different aggregations are

2313

# needed for different sets of metrics associated with that monitored

2314

# resource type. A monitored resource and metric pair may only be used once

2315

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2316

{ # Configuration of a specific monitoring destination (the producer project

2317

# or the consumer project).

2318

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2319

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2320

"metrics": [ # Types of the metrics to report to this monitoring destination.

2321

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

2328

#

2329

# The following example shows how to configure monitored resources and metrics

2330

# for billing:

2331

#

2332

# monitored_resources:

2333

# - type: library.googleapis.com/branch

2334

# labels:

2335

# - key: /city

2336

# description: The city where the library branch is located in.

2337

# - key: /name

2338

# description: The name of the branch.

2339

# metrics:

2340

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

2345

# - monitored_resource: library.googleapis.com/branch

2346

# metrics:

2347

# - library.googleapis.com/book/borrowed_count

2348

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

2349

# There can be multiple consumer destinations per service, each one must have

2350

# a different monitored resource type. A metric can be used in at most

2351

# one consumer destination.

2352

{ # Configuration of a specific billing destination (Currently only support

2353

# bill against consumer project).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2354

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2355

# Each name must be defined in Service.metrics section.

2356

"A String",

2357

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2358

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2359

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2360

},

2361

],

2362

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2363

"title": "A String", # The product title for this service.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2364

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

2365

# by the client for tracking purpose. Must be no longer than 63 characters

2366

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

2367

# empty, the server may choose to generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2368

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

2369

#

2370

# Example for an API targeted for external use:

2371

#

2372

# name: calendar.googleapis.com

2373

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2374

# providers:

2375

# - id: google_calendar_auth

2376

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2377

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2378

# rules:

2379

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2380

# requirements:

2381

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2382

"rules": [ # A list of authentication rules that apply to individual API methods.

2383

#

2384

# **NOTE:** All service configuration rules follow "last one wins" order.

2385

{ # Authentication rules for the service.

2386

#

2387

# By default, if a method has any authentication requirements, every request

2388

# must include a valid credential matching one of the requirements.

2389

# It's an error to include more than one kind of credential in a single

2390

# request.

2391

#

2392

# If a method doesn't have any auth requirements, request credentials will be

2393

# ignored.

2394

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

2395

# there are scopes defined for "Read-only access to Google Calendar" and

2396

# "Access to Cloud Platform". Users can consent to a scope for an application,

2397

# giving it permission to access that data on their behalf.

2398

#

2399

# OAuth scope specifications should be fairly coarse grained; a user will need

2400

# to see and understand the text description of what your scope means.

2401

#

2402

# In most cases: use one or at most two OAuth scopes for an entire family of

2403

# products. If your product has multiple APIs, you should probably be sharing

2404

# the OAuth scope across all of those APIs.

2405

#

2406

# When you need finer grained OAuth consent screens: talk with your product

2407

# management about how developers will use them in practice.

2408

#

2409

# Please note that even though each of the canonical scopes is enough for a

2410

# request to be accepted and passed to the backend, a request can still fail

2411

# due to the backend requiring additional scopes or permissions.

2412

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

2413

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

2418

# https://www.googleapis.com/auth/calendar.read

2419

},

2420

"requirements": [ # Requirements for additional authentication providers.

2421

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2422

# [JSON Web Token

2423

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2424

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2429

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

2430

# implemented and accepted in all the runtime components.

2431

#

2432

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2433

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2434

# that are allowed to access. A JWT containing any of these audiences will

2435

# be accepted. When this setting is absent, only JWTs with audience

2436

# "https://Service_name/API_name"

2437

# will be accepted. For example, if no audiences are in the setting,

2438

# LibraryService API will only accept JWTs with the following audience

2439

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2444

# bookstore_web.apps.googleusercontent.com

2445

},

2446

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2447

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2448

"selector": "A String", # Selects the methods to which this rule applies.

2449

#

2450

# Refer to selector for syntax details.

2451

},

2452

],

2453

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2454

{ # Configuration for an authentication provider, including support for

2455

# [JSON Web Token

2456

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2457

"jwtLocations": [ # Defines the locations to extract the JWT.

2458

#

2459

# JWT locations can be either from HTTP headers or URL query parameters.

2460

# The rule is that the first match wins. The checking order is: checking

2461

# all headers first, then URL query parameters.

2462

#

2463

# If not specified, default to use following 3 locations:

2464

# 1) Authorization: Bearer

2465

# 2) x-goog-iap-jwt-assertion

2466

# 3) access_token query parameter

2467

#

2468

# Default locations can be specified as followings:

2469

# jwt_locations:

2470

# - header: Authorization

2471

# value_prefix: "Bearer "

2472

# - header: x-goog-iap-jwt-assertion

2473

# - query: access_token

2474

{ # Specifies a location to extract JWT from an API request.

2475

"query": "A String", # Specifies URL query parameter name to extract JWT token.

2476

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

2477

# Only applies to "in" header type. Must be empty for "in" query type.

2478

# If not empty, the header value has to match (case sensitive) this prefix.

2479

# If not matched, JWT will not be extracted. If matched, JWT will be

2480

# extracted after the prefix is removed.

2481

#

2482

# For example, for "Authorization: Bearer {JWT}",

2483

# value_prefix="Bearer " with a space at the end.

2484

"header": "A String", # Specifies HTTP header name to extract JWT token.

2485

},

2486

],

2487

"audiences": "A String", # The list of JWT

2488

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2489

# that are allowed to access. A JWT containing any of these audiences will

2490

# be accepted. When this setting is absent, JWTs with audiences:

2491

# - "https://[service.name]/[google.protobuf.Api.name]"

2492

# - "https://[service.name]/"

2493

# will be accepted.

2494

# For example, if no audiences are in the setting, LibraryService API will

2495

# accept JWTs with the following audiences:

2496

# -

2497

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

2498

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2503

# bookstore_web.apps.googleusercontent.com

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2504

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

2505

# [OpenID

2506

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

2507

# Optional if the key set document:

2508

# - can be retrieved from

2509

# [OpenID

2510

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

2511

# the issuer.

2512

# - can be inferred from the email domain of the issuer (e.g. a Google

2513

# service account).

2514

#

2515

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2516

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

2517

# `AuthRequirement.provider_id`.

2518

#

2519

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2520

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

2521

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2522

"issuer": "A String", # Identifies the principal that issued the JWT. See

2523

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

2524

# Usually a URL or an email address.

2525

#

2526

# Example: https://securetoken.google.com

2527

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

2532

"rules": [ # A list of usage rules that apply to individual API methods.

2533

#

2534

# **NOTE:** All service configuration rules follow "last one wins" order.

2535

{ # Usage configuration rules for the service.

2536

#

2537

# NOTE: Under development.

2538

#

2539

#

2540

# Use this rule to configure unregistered calls for the service. Unregistered

2541

# calls are calls that do not contain consumer project identity.

2542

# (Example: calls that do not contain an API key).

2543

# By default, API methods do not allow unregistered calls, and each method call

2544

# must be identified by a consumer project identity. Use this rule to

2545

# allow/disallow unregistered calls.

2546

#

2547

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

2553

#

2554

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

2559

# allow_unregistered_calls: true

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2560

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2561

# methods in all APIs.

2562

#

2563

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2564

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

2565

# plane features, such as quota and billing, will not be available.

2566

# This flag is used by Google Cloud Endpoints to bypass checks for internal

2567

# methods, such as service health check methods.

2568

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

2569

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2570

},

2571

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2572

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

2573

#

2574

#

2575

# Use this field to configure per-product per-project service identity.

2576

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

2581

# display_name: "Cloud XXX Service Agent"

2582

# description: "Used as the identity of Cloud XXX to access resources"

2583

"displayName": "A String", # Optional. A user-specified name for the service account.

2584

# Must be less than or equal to 100 UTF-8 bytes.

2585

"description": "A String", # Optional. A user-specified opaque description of the service account.

2586

# Must be less than or equal to 256 UTF-8 bytes.

2587

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

2588

#

2589

# An example name would be:

2590

# `projects/123456789`

2591

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2592

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

2593

# service producer.

2594

#

2595

# Google Service Management currently only supports

2596

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2597

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2598

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2599

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2600

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2601

# service. Each requirement is of the form <service.name>/<requirement-id>;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2602

# for example 'serviceusage.googleapis.com/billing-enabled'.

2603

"A String",

2604

],

2605

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2606

"configVersion": 42, # The semantic version of the service configuration. The config version

2607

# affects the interpretation of the service configuration. For example,

2608

# certain features are enabled by default for certain config versions.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2609

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2610

# The latest config version is `3`.

2611

"producerProjectId": "A String", # The Google project that owns this service.

2612

"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]

2613

# HttpRule, each specifying the mapping of an RPC method

2614

# to one or more HTTP REST API methods.

2615

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2616

#

2617

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2618

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2619

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2620

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

2621

# more HTTP REST endpoints. It allows developers to build a single API service

2622

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

2623

# APIs](https://github.com/googleapis/googleapis),

2624

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

2625

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

2626

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

2627

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2628

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2629

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

2630

# how different portions of the gRPC request message are mapped to the URL

2631

# path, URL query parameters, and HTTP request body. It also controls how the

2632

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

2633

# typically specified as an `google.api.http` annotation on the gRPC method.

2634

#

2635

# Each mapping specifies a URL path template and an HTTP method. The path

2636

# template may refer to one or more fields in the gRPC request message, as long

2637

# as each field is a non-repeated field with a primitive (non-message) type.

2638

# The path template controls how fields of the request message are mapped to

2639

# the URL path.

2640

#

2641

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2642

#

2643

# service Messaging {

2644

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2645

# option (google.api.http) = {

2646

# get: "/v1/{name=messages/*}"

2647

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2648

# }

2649

# }

2650

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2651

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2652

# }

2653

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2654

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2655

# }

2656

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2657

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2658

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2659

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2660

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2661

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2662

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2663

# Any fields in the request message which are not bound by the path template

2664

# automatically become HTTP query parameters if there is no HTTP request body.

2665

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2666

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2667

# service Messaging {

2668

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2669

# option (google.api.http) = {

2670

# get:"/v1/messages/{message_id}"

2671

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2672

# }

2673

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2674

# message GetMessageRequest {

2675

# message SubMessage {

2676

# string subfield = 1;

2677

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2678

# string message_id = 1; // Mapped to URL path.

2679

# int64 revision = 2; // Mapped to URL query parameter `revision`.

2680

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2681

# }

2682

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2683

# This enables a HTTP JSON to RPC mapping as below:

2684

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2685

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2686

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2687

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2688

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

2689

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2690

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2691

# Note that fields which are mapped to URL query parameters must have a

2692

# primitive type or a repeated primitive type or a non-repeated message type.

2693

# 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^]

2694

# 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]

2695

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2696

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2697

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2698

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2699

# specifies the mapping. Consider a REST update method on the

2700

# message resource collection:

2701

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2702

# service Messaging {

2703

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2704

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2705

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2711

# string message_id = 1; // mapped to the URL

2712

# Message message = 2; // mapped to the body

2713

# }

2714

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2715

# The following HTTP JSON to RPC mapping is enabled, where the

2716

# representation of the JSON in the request body is determined by

2717

# protos JSON encoding:

2718

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2719

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2720

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2721

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2722

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2723

#

2724

# The special name `*` can be used in the body mapping to define that

2725

# every field not bound by the path template should be mapped to the

2726

# request body. This enables the following alternative definition of

2727

# the update method:

2728

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2729

# service Messaging {

2730

# rpc UpdateMessage(Message) returns (Message) {

2731

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2732

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

2739

# string text = 2;

2740

# }

2741

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2742

#

2743

# The following HTTP JSON to RPC mapping is enabled:

2744

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2745

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2746

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2747

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2748

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2749

#

2750

# Note that when using `*` in the body mapping, it is not possible to

2751

# 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]

2752

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2753

# defining REST APIs. The common usage of `*` is in custom methods

2754

# which don't use the URL at all for transferring data.

2755

#

2756

# It is possible to define multiple HTTP methods for one RPC by using

2757

# the `additional_bindings` option. Example:

2758

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2759

# service Messaging {

2760

# rpc GetMessage(GetMessageRequest) returns (Message) {

2761

# option (google.api.http) = {

2762

# get: "/v1/messages/{message_id}"

2763

# additional_bindings {

2764

# get: "/v1/users/{user_id}/messages/{message_id}"

2765

# }

2766

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2767

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2768

# }

2769

# message GetMessageRequest {

2770

# string message_id = 1;

2771

# string user_id = 2;

2772

# }

2773

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2774

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2775

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2776

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2777

# -----|-----

2778

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2779

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

2780

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2781

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2782

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2783

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2784

# 1. Leaf request fields (recursive expansion nested messages in the request

2785

# message) are classified into three categories:

2786

# - Fields referred by the path template. They are passed via the URL path.

2787

# - Fields referred by the HttpRule.body. They are passed via the HTTP

2788

# request body.

2789

# - All other fields are passed via the URL query parameters, and the

2790

# parameter name is the field path in the request message. A repeated

2791

# field can be represented as multiple query parameters under the same

2792

# name.

2793

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

2794

# are passed via URL path and HTTP request body.

2795

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

2796

# fields are passed via URL path and URL query parameters.

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

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2799

#

2800

# Template = "/" Segments [ Verb ] ;

2801

# Segments = Segment { "/" Segment } ;

2802

# Segment = "*" | "**" | LITERAL | Variable ;

2803

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2804

# FieldPath = IDENT { "." IDENT } ;

2805

# Verb = ":" LITERAL ;

2806

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2807

# The syntax `*` matches a single URL path segment. The syntax `**` matches

2808

# zero or more URL path segments, which must be the last part of the URL path

2809

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2810

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2811

# The syntax `Variable` matches part of the URL path as specified by its

2812

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2813

# matches a single path segment, its template may be omitted, e.g. `{var}`

2814

# is equivalent to `{var=*}`.

2815

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2816

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

2817

# contains any reserved character, such characters should be percent-encoded

2818

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2819

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2820

# If a variable contains exactly one path segment, such as `"{var}"` or

2821

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

2822

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

2823

# server side does the reverse decoding. Such variables show up in the

2824

# [Discovery

2825

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2826

# `{var}`.

2827

#

2828

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

2829

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

2830

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

2831

# The server side does the reverse decoding, except "%2F" and "%2f" are left

2832

# unchanged. Such variables show up in the

2833

# [Discovery

2834

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2835

# `{+var}`.

2836

#

2837

# ## Using gRPC API Service Configuration

2838

#

2839

# gRPC API Service Configuration (service config) is a configuration language

2840

# for configuring a gRPC service to become a user-facing product. The

2841

# service config is simply the YAML representation of the `google.api.Service`

2842

# proto message.

2843

#

2844

# As an alternative to annotating your proto file, you can configure gRPC

2845

# transcoding in your service config YAML files. You do this by specifying a

2846

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

2847

# effect as the proto annotation. This can be particularly useful if you

2848

# have a proto that is reused in multiple services. Note that any transcoding

2849

# specified in the service config will override any matching transcoding

2850

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

2857

# - selector: example.v1.Messaging.GetMessage

2858

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

2863

# proto to JSON conversion must follow the [proto3

2864

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

2865

#

2866

# While the single segment variable follows the semantics of

2867

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2868

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

2869

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

2870

# does not expand special characters like `?` and `#`, which would lead

2871

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

2872

# for multi segment variables.

2873

#

2874

# The path variables **must not** refer to any repeated or mapped field,

2875

# because client libraries are not capable of handling such variable expansion.

2876

#

2877

# The path variables **must not** capture the leading "/" character. The reason

2878

# is that the most common use case "{var}" does not capture the leading "/"

2879

# character. For consistency, all path variables must share the same behavior.

2880

#

2881

# Repeated message fields must not be mapped to URL query parameters, because

2882

# no client library can support such complicated mapping.

2883

#

2884

# If an API needs to use a JSON array for request or response body, it can map

2885

# the request or response body to a repeated field. However, some gRPC

2886

# Transcoding implementations may not support this feature.

2887

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

2888

# body, or `*` for mapping all request fields not captured by the path

2889

# pattern to the HTTP body, or omitted for not having any HTTP request body.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2890

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2891

# NOTE: the referred field must be present at the top-level of the request

2892

# message type.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2893

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

2894

# resources.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2895

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2896

# not contain an `additional_bindings` field themselves (that is,

2897

# the nesting may only be one level deep).

2898

# Object with schema name: HttpRule

2899

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2900

"selector": "A String", # Selects a method to which this rule applies.

2901

#

2902

# Refer to selector for syntax details.

2903

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

2904

# response body. When omitted, the entire response message will be used

2905

# as the HTTP response body.

2906

#

2907

# NOTE: The referred field must be present at the top-level of the response

2908

# message type.

2909

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

2910

# half-duplex streaming method.

2911

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2912

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2913

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2914

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

2915

# included in the `pattern` field, such as HEAD, or "*" to leave the

2916

# HTTP method unspecified for this rule. The wild-card rule is useful

2917

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2918

"path": "A String", # The path matched by this custom verb.

2919

"kind": "A String", # The name of this custom HTTP verb.

2920

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2921

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2922

},

2923

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2924

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2925

# cases of single segment matches in reserved expansion, where "%2F" will be

2926

# left encoded.

2927

#

2928

# The default behavior is to not decode RFC 6570 reserved characters in multi

2929

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2930

},

2931

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2932

# of the google.protobuf.Api needs to be provided by the configuration

2933

# author, as the remaining fields will be derived from the IDL during the

2934

# normalization process. It is an error to specify an API interface here

2935

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2936

{ # Api is a light-weight descriptor for an API Interface.

2937

#

2938

# Interfaces are also described as "protocol buffer services" in some contexts,

2939

# such as by the "service" keyword in a .proto file, but they are different

2940

# from API Services, which represent a concrete implementation of an interface

2941

# as opposed to simply a description of methods and bindings. They are also

2942

# sometimes simply referred to as "APIs" in other contexts, such as the name of

2943

# this message itself. See https://cloud.google.com/apis/design/glossary for

2944

# detailed terminology.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

2945

"name": "A String", # The fully qualified name of this interface, including package name

2946

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2947

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2948

# message.

2949

# protobuf element, like the file in which it is defined.

2950

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2951

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2952

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2953

"mixins": [ # Included interfaces. See Mixin.

2954

{ # Declares an API Interface to be included in this interface. The including

2955

# interface must redeclare all the methods from the included interface, but

2956

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2957

#

2958

# - If after comment and whitespace stripping, the documentation

2959

# string of the redeclared method is empty, it will be inherited

2960

# from the original method.

2961

#

2962

# - Each annotation belonging to the service config (http,

2963

# visibility) which is not set in the redeclared method will be

2964

# inherited.

2965

#

2966

# - If an http annotation is inherited, the path pattern will be

2967

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

2968

# version of the including interface plus the root path if

2969

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2970

#

2971

# Example of a simple mixin:

2972

#

2973

# package google.acl.v1;

2974

# service AccessControl {

2975

# // Get the underlying ACL object.

2976

# rpc GetAcl(GetAclRequest) returns (Acl) {

2977

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2982

# service Storage {

2983

# // rpc GetAcl(GetAclRequest) returns (Acl);

2984

#

2985

# // Get a data record.

2986

# rpc GetData(GetDataRequest) returns (Data) {

2987

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2992

#

2993

# apis:

2994

# - name: google.storage.v2.Storage

2995

# mixins:

2996

# - name: google.acl.v1.AccessControl

2997

#

2998

# The mixin construct implies that all methods in `AccessControl` are

2999

# also declared with same name and request/response types in

3000

# `Storage`. A documentation generator or annotation processor will

3001

# see the effective `Storage.GetAcl` method after inherting

3002

# documentation and annotations as follows:

3003

#

3004

# service Storage {

3005

# // Get the underlying ACL object.

3006

# rpc GetAcl(GetAclRequest) returns (Acl) {

3007

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3013

#

3014

# If the `root` field in the mixin is specified, it should be a

3015

# relative path under which inherited HTTP paths are placed. Example:

3016

#

3017

# apis:

3018

# - name: google.storage.v2.Storage

3019

# mixins:

3020

# - name: google.acl.v1.AccessControl

3021

# root: acls

3022

#

3023

# This implies the following inherited HTTP annotation:

3024

#

3025

# service Storage {

3026

# // Get the underlying ACL object.

3027

# rpc GetAcl(GetAclRequest) returns (Acl) {

3028

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3033

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3034

"name": "A String", # The fully qualified name of the interface which is included.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3035

},

3036

],

3037

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3038

"version": "A String", # A version string for this interface. If specified, must have the form

3039

# `major-version.minor-version`, as in `1.10`. If the minor version is

3040

# omitted, it defaults to zero. If the entire version field is empty, the

3041

# major version is derived from the package name, as outlined below. If the

3042

# field is not empty, the version in the package name will be verified to be

3043

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3044

#

3045

# The versioning schema uses [semantic

3046

# versioning](http://semver.org) where the major version number

3047

# indicates a breaking change and the minor version an additive,

3048

# non-breaking change. Both version numbers are signals to users

3049

# what to expect from different versions, and should be carefully

3050

# chosen based on the product plan.

3051

#

3052

# The major version is also reflected in the package name of the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3053

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3054

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3055

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3056

# experimental, non-GA interfaces.

3057

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3058

{ # A protocol buffer option, which can be attached to a message, field,

3059

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3060

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3061

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3062

# For custom options, it should be the fully-qualified name. For example,

3063

# `"google.api.http"`.

3064

"value": { # The option's value packed in an Any message. If the value is a primitive,

3065

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3066

# should be used. If the value is an enum, it should be stored as an int32

3067

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3068

"a_key": "", # Properties of the object. Contains field @type with type URL.

3069

},

3070

},

3071

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3072

"methods": [ # The methods of this interface, in unspecified order.

3073

{ # Method represents a method of an API interface.

3074

"name": "A String", # The simple name of this method.

3075

"requestStreaming": True or False, # If true, the request is streamed.

3076

"responseTypeUrl": "A String", # The URL of the output message type.

3077

"requestTypeUrl": "A String", # A URL of the input message type.

3078

"responseStreaming": True or False, # If true, the response is streamed.

3079

"syntax": "A String", # The source syntax of this method.

3080

"options": [ # Any metadata attached to the method.

3081

{ # A protocol buffer option, which can be attached to a message, field,

3082

# enumeration, etc.

3083

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3084

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3085

# For custom options, it should be the fully-qualified name. For example,

3086

# `"google.api.http"`.

3087

"value": { # The option's value packed in an Any message. If the value is a primitive,

3088

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3089

# should be used. If the value is an enum, it should be stored as an int32

3090

# value using the google.protobuf.Int32Value type.

3091

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3097

},

3098

],

3099

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3100

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3108

# - google.foo.v1.AnotherError

3109

"rules": [ # The list of custom error rules that apply to individual API messages.

3110

#

3111

# **NOTE:** All service configuration rules follow "last one wins" order.

3112

{ # A custom error rule.

3113

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3114

# objects of this type will be filtered when they appear in error payload.

3115

"selector": "A String", # Selects messages to which this rule applies.

3116

#

3117

# Refer to selector for syntax details.

3118

},

3119

],

3120

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

3121

"A String",

3122

],

3123

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3124

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

3125

# usage.

3126

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3127

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3128

# - The service configuration defines a set of metrics.

3129

# - For API calls, the quota.metric_rules maps methods to metrics with

3130

# corresponding costs.

3131

# - The quota.limits defines limits on the metrics, which will be used for

3132

# quota checks at runtime.

3133

#

3134

# An example quota configuration in yaml format:

3135

#

3136

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3137

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3138

#

3139

# - name: apiWriteQpsPerProject

3140

# metric: library.googleapis.com/write_calls

3141

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

3147

# # except for the UpdateBook and DeleteBook methods. These two methods

3148

# # are mapped to the write_calls metric, with the UpdateBook method

3149

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

3154

# - selector: google.example.library.v1.LibraryService.UpdateBook

3155

# metric_costs:

3156

# library.googleapis.com/write_calls: 2

3157

# - selector: google.example.library.v1.LibraryService.DeleteBook

3158

# metric_costs:

3159

# library.googleapis.com/write_calls: 1

3160

#

3161

# Corresponding Metric definition:

3162

#

3163

# metrics:

3164

# - name: library.googleapis.com/read_calls

3165

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

3170

# display_name: Write requests

3171

# metric_kind: DELTA

3172

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3173

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3174

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

3175

# or more metrics.

3176

{ # Bind API methods to metrics. Binding a method to a metric causes that

3177

# metric's configured quota behaviors to apply to the method call.

3178

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

3179

# cost applied to each metric.

3180

#

3181

# The key of the map is the metric name, and the values are the amount

3182

# increased for the metric against which the quota limits are defined.

3183

# The value must not be negative.

3184

"a_key": "A String",

3185

},

3186

"selector": "A String", # Selects the methods to which this rule applies.

3187

#

3188

# Refer to selector for syntax details.

3189

},

3190

],

3191

"limits": [ # List of `QuotaLimit` definitions for the service.

3192

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

3193

# for a limit type. There can be at most one limit for a duration and limit

3194

# type combination defined within a `QuotaGroup`.

3195

"displayName": "A String", # User-visible display name for this limit.

3196

# Optional. If not set, the UI will provide a default display name based on

3197

# the quota configuration. This field can be used to override the default

3198

# display name generated from the configuration.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3199

"description": "A String", # Optional. User-visible, extended description for this quota limit.

3200

# Should be used only when more context is needed to understand this limit

3201

# than provided by the limit's display name (see: `display_name`).

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3202

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

3203

# duration. This is the number of tokens assigned when a client

3204

# application developer activates the service for his/her project.

3205

#

3206

# Specifying a value of 0 will block all requests. This can be used if you

3207

# are provisioning quota to selected consumers and blocking others.

3208

# Similarly, a value of -1 will indicate an unlimited quota. No other

3209

# negative values are allowed.

3210

#

3211

# Used by group-based quotas only.

3212

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

3213

# the same metric will be checked together during runtime. The metric must be

3214

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3215

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

3216

# integer value that is the maximum number of requests allowed for the

3217

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3218

"a_key": "A String",

3219

},

3220

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

3221

# duration. Client application developers can override the default limit up

3222

# to this maximum. If specified, this value cannot be set to a value less

3223

# than the default limit. If not specified, it is set to the default limit.

3224

#

3225

# To allow clients to apply overrides with no upper bound, set this to -1,

3226

# indicating unlimited maximum quota.

3227

#

3228

# Used by group-based quotas only.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3229

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3230

#

3231

# Used by group-based quotas only.

3232

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

3233

# The free tier is the number of tokens that will be subtracted from the

3234

# billed amount when billing is enabled.

3235

# This field can only be set on a limit with duration "1d", in a billable

3236

# group; it is invalid on any other limit. If this field is not set, it

3237

# defaults to 0, indicating that there is no free tier for this service.

3238

#

3239

# Used by group-based quotas only.

3240

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

3241

# Metric.unit. The supported unit kinds are determined by the quota

3242

# backend system.

3243

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3244

# Here are some examples:

3245

# * "1/min/{project}" for quota per minute per project.

3246

#

3247

# Note: the order of unit components is insignificant.

3248

# The "1" at the beginning is required to follow the metric unit syntax.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3249

"name": "A String", # Name of the quota limit.

3250

#

3251

# The name must be provided, and it must be unique within the service. The

3252

# name can only include alphanumeric characters as well as '-'.

3253

#

3254

# The maximum length of the limit name is 64 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3259

{ # Defines a metric type and its schema. Once a metric descriptor is created,

3260

# deleting or altering it stops data collection and makes the metric type's

3261

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3262

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3263

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3264

# This field is optional but it is recommended to be set for any metrics

3265

# associated with user-visible concepts, such as Quota.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3266

"description": "A String", # A detailed description of the metric, which can be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3267

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3268

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3269

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3270

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3271

"labels": [ # The set of labels that can be used to describe a specific

3272

# instance of this metric type. For example, the

3273

# `appengine.googleapis.com/http/server/response_latencies` metric

3274

# type has a label for the HTTP response code, `response_code`, so

3275

# you can look at latencies for successful responses or just

3276

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3277

{ # A description of a label.

3278

"valueType": "A String", # The type of data that can be assigned to the label.

3279

"description": "A String", # A human-readable description for the label.

3280

"key": "A String", # The label key.

3281

},

3282

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3283

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3284

"monitoredResourceTypes": [ # Read-only. If present, then a time

3285

# series, which is identified partially by

3286

# a metric type and a MonitoredResourceDescriptor, that is associated

3287

# with this metric type can only be associated with one of the monitored

3288

# resource types listed here.

3289

"A String",

3290

],

3291

"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.

3292

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

3293

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

3294

# age are guaranteed to be ingested and available to be read, excluding

3295

# data loss due to errors.

3296

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

3297

# periodically, consecutive data points are stored at this time interval,

3298

# excluding data loss due to errors. Metrics with a higher granularity have

3299

# a smaller sampling period.

3300

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3301

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3302

# URL-encoded. All user-defined metric types have the DNS name

3303

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

3304

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3305

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3306

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3307

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3308

# "appengine.googleapis.com/http/server/response_latencies"

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3309

"unit": "A String", # The units in which the metric value is reported. It is only applicable

3310

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

3311

# defines the representation of the stored metric values.

3312

#

3313

# Different systems may scale the values to be more easily displayed (so a

3314

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

3315

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

3316

# `KBy`, then the value of the metric is always in thousands of bytes, no

3317

# matter how it may be displayed..

3318

#

3319

# If you want a custom metric to record the exact number of CPU-seconds used

3320

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

3321

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

3322

# CPU-seconds, then the value is written as `12005`.

3323

#

3324

# Alternatively, if you want a custom metric to record data in a more

3325

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

3326

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

3327

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

3328

#

3329

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3330

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3331

#

3332

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

3342

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

3350

# * `Y` yotta (10^24)

3351

#

3352

# * `m` milli (10^-3)

3353

# * `u` micro (10^-6)

3354

# * `n` nano (10^-9)

3355

# * `p` pico (10^-12)

3356

# * `f` femto (10^-15)

3357

# * `a` atto (10^-18)

3358

# * `z` zepto (10^-21)

3359

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3366

#

3367

# **Grammar**

3368

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3369

# The grammar also includes these connectors:

3370

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3371

# * `/` division or ratio (as an infix operator). For examples,

3372

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

3373

# have `/s` in a metric `unit`; rates should always be computed at

3374

# query time from the underlying cumulative or delta value).

3375

# * `.` multiplication or composition (as an infix operator). For

3376

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3377

#

3378

# The grammar for a unit is as follows:

3379

#

3380

# Expression = Component { "." Component } { "/" Component } ;

3381

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3382

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

3388

#

3389

# Notes:

3390

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3391

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

3392

# is used alone, then the unit is equivalent to `1`. For examples,

3393

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3394

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3395

# containing `{` or `}`.

3396

# * `1` represents a unitary [dimensionless

3397

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

3398

# as in `1/s`. It is typically used when none of the basic units are

3399

# appropriate. For example, "new users per day" can be represented as

3400

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

3401

# users). Alternatively, "thousands of page views per day" would be

3402

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

3403

# value of `5.3` would mean "5300 page views per day").

3404

# * `%` represents dimensionless value of 1/100, and annotates values giving

3405

# a percentage (so the metric values are typically in the range of 0..100,

3406

# and a metric value `3` means "3 percent").

3407

# * `10^2.%` indicates a metric contains a ratio, typically in the range

3408

# 0..1, that will be multiplied by 100 and displayed as a percentage

3409

# (so a metric value `0.03` means "3 percent").

3410

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3411

},

3412

],

3413

"enums": [ # A list of all enum types included in this API service. Enums

3414

# referenced directly or indirectly by the `apis` are automatically

3415

# included. Enums which are not referenced but shall be included

3416

# should be listed here by name. Example:

3417

#

3418

# enums:

3419

# - name: google.someapi.v1.SomeEnum

3420

{ # Enum type definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3421

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3422

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3423

# protobuf element, like the file in which it is defined.

3424

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3425

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3426

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3427

"options": [ # Protocol buffer options.

3428

{ # A protocol buffer option, which can be attached to a message, field,

3429

# enumeration, etc.

3430

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3431

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3432

# For custom options, it should be the fully-qualified name. For example,

3433

# `"google.api.http"`.

3434

"value": { # The option's value packed in an Any message. If the value is a primitive,

3435

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3436

# should be used. If the value is an enum, it should be stored as an int32

3437

# value using the google.protobuf.Int32Value type.

3438

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3443

"enumvalue": [ # Enum value definitions.

3444

{ # Enum value definition.

3445

"options": [ # Protocol buffer options.

3446

{ # A protocol buffer option, which can be attached to a message, field,

3447

# enumeration, etc.

3448

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3449

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3450

# For custom options, it should be the fully-qualified name. For example,

3451

# `"google.api.http"`.

3452

"value": { # The option's value packed in an Any message. If the value is a primitive,

3453

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3454

# should be used. If the value is an enum, it should be stored as an int32

3455

# value using the google.protobuf.Int32Value type.

3456

"a_key": "", # Properties of the object. Contains field @type with type URL.

3457

},

3458

},

3459

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3460

"number": 42, # Enum value number.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3461

"name": "A String", # Enum value name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3462

},

3463

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3464

},

3465

],

3466

"types": [ # A list of all proto message types included in this API service.

3467

# Types referenced directly or indirectly by the `apis` are

3468

# automatically included. Messages which are not referenced but

3469

# shall be included, such as types used by the `google.protobuf.Any` type,

3470

# should be listed here by name. Example:

3471

#

3472

# types:

3473

# - name: google.protobuf.Int32

3474

{ # A protocol buffer message type.

3475

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3476

"A String",

3477

],

3478

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3479

"fields": [ # The list of fields.

3480

{ # A single field of a message type.

3481

"kind": "A String", # The field type.

3482

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3483

# types. The first type has index 1; zero means the type is not in the list.

3484

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3485

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3486

"name": "A String", # The field name.

3487

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3488

"jsonName": "A String", # The field JSON name.

3489

"number": 42, # The field number.

3490

"cardinality": "A String", # The field cardinality.

3491

"options": [ # The protocol buffer options.

3492

{ # A protocol buffer option, which can be attached to a message, field,

3493

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3494

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3495

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3496

# For custom options, it should be the fully-qualified name. For example,

3497

# `"google.api.http"`.

3498

"value": { # The option's value packed in an Any message. If the value is a primitive,

3499

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3500

# should be used. If the value is an enum, it should be stored as an int32

3501

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3502

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3507

},

3508

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3509

"syntax": "A String", # The source syntax.

3510

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3511

# protobuf element, like the file in which it is defined.

3512

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3513

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3514

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3515

"options": [ # The protocol buffer options.

3516

{ # A protocol buffer option, which can be attached to a message, field,

3517

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3518

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3519

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3520

# For custom options, it should be the fully-qualified name. For example,

3521

# `"google.api.http"`.

3522

"value": { # The option's value packed in an Any message. If the value is a primitive,

3523

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3524

# should be used. If the value is an enum, it should be stored as an int32

3525

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3526

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3532

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3533

#

3534

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3535

# producer and consumer projects. In the example, the `activity_history`

3536

# log is sent to both the producer and consumer projects, whereas the

3537

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3538

#

3539

# monitored_resources:

3540

# - type: library.googleapis.com/branch

3541

# labels:

3542

# - key: /city

3543

# description: The city where the library branch is located in.

3544

# - key: /name

3545

# description: The name of the branch.

3546

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3547

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3548

# labels:

3549

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3550

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3551

# logging:

3552

# producer_destinations:

3553

# - monitored_resource: library.googleapis.com/branch

3554

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3555

# - activity_history

3556

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3557

# consumer_destinations:

3558

# - monitored_resource: library.googleapis.com/branch

3559

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3560

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3561

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3562

# There can be multiple producer destinations, each one must have a

3563

# different monitored resource type. A log can be used in at most

3564

# one producer destination.

3565

{ # Configuration of a specific logging destination (the producer project

3566

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3567

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3568

# Service.monitored_resources section.

3569

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3570

# be defined in the Service.logs section. If the log name is

3571

# not a domain scoped name, it will be automatically prefixed with

3572

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

3578

# There can be multiple consumer destinations, each one must have a

3579

# different monitored resource type. A log can be used in at most

3580

# one consumer destination.

3581

{ # Configuration of a specific logging destination (the producer project

3582

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3583

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3584

# Service.monitored_resources section.

3585

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3586

# be defined in the Service.logs section. If the log name is

3587

# not a domain scoped name, it will be automatically prefixed with

3588

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3594

"name": "A String", # The service name, which is a DNS-like logical identifier for the

3595

# service, such as `calendar.googleapis.com`. The service name

3596

# typically goes through DNS verification to make sure the owner

3597

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3598

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

3599

#

3600

# Example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3601

# <pre><code>documentation:

3602

# summary: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3603

# The Google Calendar API gives access

3604

# to most calendar features.

3605

# pages:

3606

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3607

# content: &#40;== include google/foo/overview.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3608

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3609

# content: &#40;== include google/foo/tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3610

# subpages;

3611

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3612

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3613

# rules:

3614

# - selector: google.calendar.Calendar.Get

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3615

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3616

# ...

3617

# - selector: google.calendar.Calendar.Put

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3618

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3619

# ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3620

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3621

# Documentation is provided in markdown syntax. In addition to

3622

# standard markdown features, definition lists, tables and fenced

3623

# code blocks are supported. Section headers can be provided and are

3624

# interpreted relative to the section nesting of the context where

3625

# a documentation fragment is embedded.

3626

#

3627

# Documentation from the IDL is merged with documentation defined

3628

# via the config at normalization time, where documentation provided

3629

# by config rules overrides IDL provided.

3630

#

3631

# A number of constructs specific to the API platform are supported

3632

# in documentation text.

3633

#

3634

# In order to reference a proto element, the following

3635

# notation can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3636

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3637

# To override the display text used for the link, this can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3638

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3639

# Text can be excluded from doc using the following notation:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3640

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3641

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3642

# A few directives are available in documentation. Note that

3643

# directives must appear on a single line to be properly

3644

# identified. The `include` directive includes a markdown file from

3645

# an external source:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3646

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3647

# The `resource_for` directive marks a message to be the resource of

3648

# a collection in REST view. If it is not specified, tools attempt

3649

# to infer the resource from the operations in a collection:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3650

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3651

# The directive `suppress_warning` does not directly affect documentation

3652

# and is documented together with service config validation.

3653

"rules": [ # A list of documentation rules that apply to individual API elements.

3654

#

3655

# **NOTE:** All service configuration rules follow "last one wins" order.

3656

{ # A documentation rule provides information about individual API elements.

3657

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3658

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

3659

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3660

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3661

# qualified name of the element which may end in "*", indicating a wildcard.

3662

# Wildcards are only allowed at the end and for a whole component of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3663

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

3664

# wildcard will match one or more components. To specify a default for all

3665

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3666

},

3667

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3668

"documentationRootUrl": "A String", # The URL to the root of documentation.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3669

"summary": "A String", # A short summary of what the service does. Can only be provided by

3670

# plain text.

3671

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

3672

# from the yaml file) is not suitable. This can be seen in any fully

3673

# specified service urls as well as sections that show a base that other

3674

# urls are relative to.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3675

"overview": "A String", # Declares a single overview page. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3676

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3677

# summary: ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3678

# overview: &#40;== include overview.md ==&#41;

3679

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3680

# This is a shortcut for the following declaration (using pages style):

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3681

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3682

# summary: ...

3683

# pages:

3684

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3685

# content: &#40;== include overview.md ==&#41;

3686

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3687

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3688

"pages": [ # The top level pages for the documentation set.

3689

{ # Represents a documentation page. A page can contain subpages to represent

3690

# nested documentation set structure.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3691

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

3692

# ==&#41;</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3693

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3694

# honored in the generated docset.

3695

# Object with schema name: Page

3696

],

3697

"name": "A String", # The name of the page. It will be used as an identity of the page to

3698

# generate URI of the page, text of the link to this page in navigation,

3699

# etc. The full page name (start from the root page name to this page

3700

# concatenated with `.`) can be used as reference to the page in your

3701

# documentation. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3702

# <pre><code>pages:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3703

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3704

# content: &#40;== include tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3705

# subpages:

3706

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3707

# content: &#40;== include tutorial_java.md ==&#41;

3708

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3709

# You can reference `Java` page using Markdown reference link syntax:

3710

# `Java`.

3711

},

3712

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3713

},

3714

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

3715

"sourceFiles": [ # All files used during config generation.

3716

{

3717

"a_key": "", # Properties of the object. Contains field @type with type URL.

3718

},

3719

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3720

},

3721

"systemTypes": [ # A list of all proto message types included in this API service.

3722

# It serves similar purpose as [google.api.Service.types], except that

3723

# these types are not needed by user-defined APIs. Therefore, they will not

3724

# show up in the generated discovery doc. This field should only be used

3725

# to define system APIs in ESF.

3726

{ # A protocol buffer message type.

3727

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3728

"A String",

3729

],

3730

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3731

"fields": [ # The list of fields.

3732

{ # A single field of a message type.

3733

"kind": "A String", # The field type.

3734

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3735

# types. The first type has index 1; zero means the type is not in the list.

3736

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3737

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3738

"name": "A String", # The field name.

3739

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3740

"jsonName": "A String", # The field JSON name.

3741

"number": 42, # The field number.

3742

"cardinality": "A String", # The field cardinality.

3743

"options": [ # The protocol buffer options.

3744

{ # A protocol buffer option, which can be attached to a message, field,

3745

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3746

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3747

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3748

# For custom options, it should be the fully-qualified name. For example,

3749

# `"google.api.http"`.

3750

"value": { # The option's value packed in an Any message. If the value is a primitive,

3751

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3752

# should be used. If the value is an enum, it should be stored as an int32

3753

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3754

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3759

},

3760

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3761

"syntax": "A String", # The source syntax.

3762

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3763

# protobuf element, like the file in which it is defined.

3764

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3765

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3766

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3767

"options": [ # The protocol buffer options.

3768

{ # A protocol buffer option, which can be attached to a message, field,

3769

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3770

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3771

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3772

# For custom options, it should be the fully-qualified name. For example,

3773

# `"google.api.http"`.

3774

"value": { # The option's value packed in an Any message. If the value is a primitive,

3775

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3776

# should be used. If the value is an enum, it should be stored as an int32

3777

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3778

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

3793

# - google.rpc.context.OriginContext

3794

#

3795

# The above specifies that all methods in the API request

3796

# `google.rpc.context.ProjectContext` and

3797

# `google.rpc.context.OriginContext`.

3798

#

3799

# Available context types are defined in package

3800

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3801

#

3802

# This also provides mechanism to whitelist any protobuf message extension that

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3803

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

3804

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3805

# 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"

3813

# allowed_request_extensions:

3814

# - google.foo.v1.NewExtension

3815

# allowed_response_extensions:

3816

# - google.foo.v1.NewExtension

3817

#

3818

# You can also specify extension ID instead of fully qualified extension name

3819

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3820

"rules": [ # A list of RPC context rules that apply to individual API methods.

3821

#

3822

# **NOTE:** All service configuration rules follow "last one wins" order.

3823

{ # A context rule provides information about the context for an individual API

3824

# element.

3825

"provided": [ # A list of full type names of provided contexts.

3826

"A String",

3827

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3828

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3829

# side channel from backend to client.

3830

"A String",

3831

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3832

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3833

# side channel from client to backend.

3834

"A String",

3835

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3836

"requested": [ # A list of full type names of requested contexts.

3837

"A String",

3838

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3839

"selector": "A String", # Selects the methods to which this rule applies.

3840

#

3841

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3842

},

3843

],

3844

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3845

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

3846

# with the same name as the service is automatically generated to service all

3847

# defined APIs.

3848

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

3849

# A service may expose any number of endpoints, and all endpoints share the

3850

# same service configuration, such as quota configuration and monitoring

3851

# configuration.

3852

#

3853

# Example service configuration:

3854

#

3855

# name: library-example.googleapis.com

3856

# endpoints:

3857

# # Below entry makes 'google.example.library.v1.Library'

3858

# # API be served from endpoint address library-example.googleapis.com.

3859

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

3860

# # it to decide whether the subsequent cross-origin request is

3861

# # allowed to proceed.

3862

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3863

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3864

"allowCors": True or False, # Allowing

3865

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

3866

# cross-domain traffic, would allow the backends served from this endpoint to

3867

# receive and respond to HTTP OPTIONS requests. The response will be used by

3868

# the browser to determine whether the subsequent cross-origin request is

3869

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3870

"target": "A String", # The specification of an Internet routable address of API frontend that will

3871

# handle requests to this [API

3872

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

3873

# either a valid IPv4 address or a fully-qualified domain name. For example,

3874

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3875

"features": [ # The list of features enabled on this endpoint.

3876

"A String",

3877

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3878

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3879

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3880

# please specify multiple google.api.Endpoint for each of the intended

3881

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3882

#

3883

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3892

<code class="details" id="get">get(serviceName, configId, x__xgafv=None, view=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3893

<pre>Gets a service configuration (version) for a managed service.

3894

3895

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3896

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]

3897

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3898

configId: string, Required. The id of the service configuration resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3899

3900

This field must be specified for the server to return all fields, including

3901

`SourceInfo`. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3902

x__xgafv: string, V1 error format.

3903

Allowed values

3904

1 - v1 error format

3905

2 - v2 error format

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3906

view: string, Specifies which parts of the Service Config should be returned in the

3907

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3908

3909

Returns:

3910

An object of the form:

3911

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3912

{ # `Service` is the root object of Google service configuration schema. It

3913

# describes basic information about a service, such as the name and the

3914

# title, and delegates other aspects to sub-sections. Each sub-section is

3915

# either a proto message or a repeated proto message that configures a

3916

# 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]

3921

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3922

# name: calendar.googleapis.com

3923

# title: Google Calendar API

3924

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3925

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3926

# authentication:

3927

# providers:

3928

# - id: google_calendar_auth

3929

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3930

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3931

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3932

# - selector: "*"

3933

# requirements:

3934

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3935

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3936

# service controller handles features like abuse, quota, billing, logging,

3937

# monitoring, etc.

3938

"environment": "A String", # The service control environment to use. If empty, no control plane

3939

# feature (like quota and billing) will be enabled.

3940

},

3941

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3942

# by the Service.monitoring and Service.logging configurations.

3943

{ # An object that describes the schema of a MonitoredResource object using a

3944

# type name and a set of labels. For example, the monitored resource

3945

# descriptor for Google Compute Engine VM instances has a type of

3946

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3947

# `"zone"` to identify particular VM instances.

3948

#

3949

# Different APIs can support different monitored resource types. APIs generally

3950

# provide a `list` method that returns the monitored resource descriptors used

3951

# by the API.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3952

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3953

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3954

# without any article or other determiners. For example,

3955

# `"Google Cloud SQL Database"`.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3956

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3957

# be used in documentation.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3958

"labels": [ # Required. A set of labels used to describe instances of this monitored

3959

# resource type. For example, an individual Google Cloud SQL database is

3960

# identified by values for the labels `"database_id"` and `"zone"`.

3961

{ # A description of a label.

3962

"valueType": "A String", # The type of data that can be assigned to the label.

3963

"description": "A String", # A human-readable description for the label.

3964

"key": "A String", # The label key.

3965

},

3966

],

3967

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

3968

"type": "A String", # Required. The monitored resource type. For example, the type

3969

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3970

# The maximum length of this value is 256 characters.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

3971

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3972

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3973

# {type} is the value of the `type` field in this object and

3974

# {project_id} is a project ID that provides API-specific context for

3975

# accessing the type. APIs that do not use project information can use the

3976

# resource name format `"monitoredResourceDescriptors/{type}"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3977

},

3978

],

3979

"logs": [ # Defines the logs used by this service.

3980

{ # A description of a log type. Example in YAML format:

3981

#

3982

# - name: library.googleapis.com/activity_history

3983

# description: The history of borrowing and returning library items.

3984

# display_name: Activity

3985

# labels:

3986

# - key: /customer_id

3987

# description: Identifier of a library customer

3988

"labels": [ # The set of labels that are available to describe a specific log entry.

3989

# Runtime requests that contain labels not specified here are

3990

# considered invalid.

3991

{ # A description of a label.

3992

"valueType": "A String", # The type of data that can be assigned to the label.

3993

"description": "A String", # A human-readable description for the label.

3994

"key": "A String", # The label key.

3995

},

3996

],

3997

"displayName": "A String", # The human-readable name for this log. This information appears on

3998

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3999

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4000

# include the following characters: upper- and lower-case alphanumeric

4001

# characters [A-Za-z0-9], and punctuation characters including

4002

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4003

"description": "A String", # A human-readable description of this log. This information appears in

4004

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4005

},

4006

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4007

"systemParameters": { # ### System parameter configuration # System parameter configuration.

4008

#

4009

# A system parameter is a special kind of parameter defined by the API

4010

# system, not by an individual API. It is typically mapped to an HTTP header

4011

# and/or a URL query parameter. This configuration specifies which methods

4012

# change the names of the system parameters.

4013

"rules": [ # Define system parameters.

4014

#

4015

# The parameters defined here will override the default parameters

4016

# implemented by the system. If this field is missing from the service

4017

# config, default system parameters will be used. Default system parameters

4018

# and names is implementation-dependent.

4019

#

4020

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4028

#

4029

#

4030

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4035

# parameters:

4036

# - name: api_key

4037

# http_header: Api-Key1

4038

# - name: api_key

4039

# http_header: Api-Key2

4040

#

4041

# **NOTE:** All service configuration rules follow "last one wins" order.

4042

{ # Define a system parameter rule mapping system parameter definitions to

4043

# methods.

4044

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4045

# For a given method call, only one of them should be used. If multiple

4046

# names are used the behavior is implementation-dependent.

4047

# If none of the specified names are present the behavior is

4048

# parameter-dependent.

4049

{ # Define a parameter's name and location. The parameter may be passed as either

4050

# an HTTP header or a URL query parameter, and if both are passed the behavior

4051

# is implementation-dependent.

4052

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4053

# sensitive.

4054

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

4055

# insensitive.

4056

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

4057

},

4058

],

4059

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4060

# methods in all APIs.

4061

#

4062

# Refer to selector for syntax details.

4063

},

4064

],

4065

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4066

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4067

"rules": [ # A list of API backend rules that apply to individual API methods.

4068

#

4069

# **NOTE:** All service configuration rules follow "last one wins" order.

4070

{ # A backend rule provides configuration for an individual API element.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4071

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

4072

# This ID token will be added in the HTTP "authorization" header, and sent

4073

# to the backend.

4074

"protocol": "A String", # The protocol used for sending a request to the backend.

4075

# The supported values are "http/1.1" and "h2".

4076

#

4077

# 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

4087

# to "h2" for improved performance.

4088

#

4089

# Configuring this field to non-default values is only supported for secure

4090

# HTTP backends. This field will be ignored for all other backends.

4091

#

4092

# See

4093

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

4094

# for more details on the supported values.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4095

"pathTranslation": "A String",

4096

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

4097

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4098

"selector": "A String", # Selects the methods to which this rule applies.

4099

#

4100

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4101

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

4102

# operation. The default is no deadline.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4103

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

4104

# varies based on the request protocol and deployment environment.

4105

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

4106

# original "Authorization" HTTP header will be preserved. If the header is

4107

# used to carry the original token and is expected by the backend, this

4108

# field must be set to true to preserve the header.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4109

"address": "A String", # The address of the API backend.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4110

#

4111

# The scheme is used to determine the backend protocol and security.

4112

# The following schemes are accepted:

4113

#

4114

# 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

4121

# may cause constrasting behaviors across platforms.

4122

#

4123

# If the port is unspecified, the default is:

4124

# - 80 for schemes without TLS

4125

# - 443 for schemes with TLS

4126

#

4127

# For HTTP backends, use protocol

4128

# to specify the protocol version.

4129

"renameTo": "A String", # Unimplemented. Do not use.

4130

#

4131

# The new name the selected proto elements should be renamed to.

4132

#

4133

# The package, the service and the method can all be renamed.

4134

# The backend server should implement the renamed proto. However, clients

4135

# should call the original method, and ESF routes the traffic to the renamed

4136

# method.

4137

#

4138

# HTTP clients should call the URL mapped to the original method.

4139

# gRPC and Stubby clients should call the original method with package name.

4140

#

4141

# For legacy reasons, ESF allows Stubby clients to call with the

4142

# short name (without the package name). However, for API Versioning(or

4143

# multiple methods mapped to the same short name), all Stubby clients must

4144

# call the method's full name with the package name, otherwise the first one

4145

# (selector) wins.

4146

#

4147

# If this `rename_to` is specified with a trailing `*`, the `selector` must

4148

# be specified with a trailing `*` as well. The all element short names

4149

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

4155

# rename_to: google.example.library.*

4156

#

4157

# The selector matches `google.example.library.v1.Library.CreateShelf` and

4158

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

4159

# `google.example.library.Library.CreateShelf` and

4160

# `google.example.library.Library.CreateBook`. It essentially renames the

4161

# proto package name section of the matched proto service and methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4162

},

4163

],

4164

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4165

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4166

#

4167

# The example below shows how to configure monitored resources and metrics

4168

# for monitoring. In the example, a monitored resource and two metrics are

4169

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4170

# to both producer and consumer projects, whereas the

4171

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4172

# consumer project.

4173

#

4174

# monitored_resources:

4175

# - type: library.googleapis.com/branch

4176

# labels:

4177

# - key: /city

4178

# description: The city where the library branch is located in.

4179

# - key: /name

4180

# description: The name of the branch.

4181

# metrics:

4182

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4187

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4192

# monitoring:

4193

# producer_destinations:

4194

# - monitored_resource: library.googleapis.com/branch

4195

# metrics:

4196

# - library.googleapis.com/book/returned_count

4197

# consumer_destinations:

4198

# - monitored_resource: library.googleapis.com/branch

4199

# metrics:

4200

# - library.googleapis.com/book/returned_count

4201

# - library.googleapis.com/book/overdue_count

4202

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4203

# There can be multiple producer destinations. A monitored resouce type may

4204

# appear in multiple monitoring destinations if different aggregations are

4205

# needed for different sets of metrics associated with that monitored

4206

# resource type. A monitored resource and metric pair may only be used once

4207

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4208

{ # Configuration of a specific monitoring destination (the producer project

4209

# or the consumer project).

4210

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4211

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4212

"metrics": [ # Types of the metrics to report to this monitoring destination.

4213

# Each type must be defined in Service.metrics section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4219

# There can be multiple consumer destinations. A monitored resouce type may

4220

# appear in multiple monitoring destinations if different aggregations are

4221

# needed for different sets of metrics associated with that monitored

4222

# resource type. A monitored resource and metric pair may only be used once

4223

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4224

{ # Configuration of a specific monitoring destination (the producer project

4225

# or the consumer project).

4226

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4227

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4228

"metrics": [ # Types of the metrics to report to this monitoring destination.

4229

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

4236

#

4237

# The following example shows how to configure monitored resources and metrics

4238

# for billing:

4239

#

4240

# monitored_resources:

4241

# - type: library.googleapis.com/branch

4242

# labels:

4243

# - key: /city

4244

# description: The city where the library branch is located in.

4245

# - key: /name

4246

# description: The name of the branch.

4247

# metrics:

4248

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

4253

# - monitored_resource: library.googleapis.com/branch

4254

# metrics:

4255

# - library.googleapis.com/book/borrowed_count

4256

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

4257

# There can be multiple consumer destinations per service, each one must have

4258

# a different monitored resource type. A metric can be used in at most

4259

# one consumer destination.

4260

{ # Configuration of a specific billing destination (Currently only support

4261

# bill against consumer project).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4262

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4263

# Each name must be defined in Service.metrics section.

4264

"A String",

4265

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4266

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4267

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4268

},

4269

],

4270

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4271

"title": "A String", # The product title for this service.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4272

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4273

# by the client for tracking purpose. Must be no longer than 63 characters

4274

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

4275

# empty, the server may choose to generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4276

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4277

#

4278

# Example for an API targeted for external use:

4279

#

4280

# name: calendar.googleapis.com

4281

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4282

# providers:

4283

# - id: google_calendar_auth

4284

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4285

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4286

# rules:

4287

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4288

# requirements:

4289

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4290

"rules": [ # A list of authentication rules that apply to individual API methods.

4291

#

4292

# **NOTE:** All service configuration rules follow "last one wins" order.

4293

{ # Authentication rules for the service.

4294

#

4295

# By default, if a method has any authentication requirements, every request

4296

# must include a valid credential matching one of the requirements.

4297

# It's an error to include more than one kind of credential in a single

4298

# request.

4299

#

4300

# If a method doesn't have any auth requirements, request credentials will be

4301

# ignored.

4302

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4303

# there are scopes defined for "Read-only access to Google Calendar" and

4304

# "Access to Cloud Platform". Users can consent to a scope for an application,

4305

# giving it permission to access that data on their behalf.

4306

#

4307

# OAuth scope specifications should be fairly coarse grained; a user will need

4308

# to see and understand the text description of what your scope means.

4309

#

4310

# In most cases: use one or at most two OAuth scopes for an entire family of

4311

# products. If your product has multiple APIs, you should probably be sharing

4312

# the OAuth scope across all of those APIs.

4313

#

4314

# When you need finer grained OAuth consent screens: talk with your product

4315

# management about how developers will use them in practice.

4316

#

4317

# Please note that even though each of the canonical scopes is enough for a

4318

# request to be accepted and passed to the backend, a request can still fail

4319

# due to the backend requiring additional scopes or permissions.

4320

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4321

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4326

# https://www.googleapis.com/auth/calendar.read

4327

},

4328

"requirements": [ # Requirements for additional authentication providers.

4329

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4330

# [JSON Web Token

4331

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4332

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4337

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

4338

# implemented and accepted in all the runtime components.

4339

#

4340

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4341

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4342

# that are allowed to access. A JWT containing any of these audiences will

4343

# be accepted. When this setting is absent, only JWTs with audience

4344

# "https://Service_name/API_name"

4345

# will be accepted. For example, if no audiences are in the setting,

4346

# LibraryService API will only accept JWTs with the following audience

4347

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4352

# bookstore_web.apps.googleusercontent.com

4353

},

4354

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4355

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4356

"selector": "A String", # Selects the methods to which this rule applies.

4357

#

4358

# Refer to selector for syntax details.

4359

},

4360

],

4361

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4362

{ # Configuration for an authentication provider, including support for

4363

# [JSON Web Token

4364

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4365

"jwtLocations": [ # Defines the locations to extract the JWT.

4366

#

4367

# JWT locations can be either from HTTP headers or URL query parameters.

4368

# The rule is that the first match wins. The checking order is: checking

4369

# all headers first, then URL query parameters.

4370

#

4371

# If not specified, default to use following 3 locations:

4372

# 1) Authorization: Bearer

4373

# 2) x-goog-iap-jwt-assertion

4374

# 3) access_token query parameter

4375

#

4376

# Default locations can be specified as followings:

4377

# jwt_locations:

4378

# - header: Authorization

4379

# value_prefix: "Bearer "

4380

# - header: x-goog-iap-jwt-assertion

4381

# - query: access_token

4382

{ # Specifies a location to extract JWT from an API request.

4383

"query": "A String", # Specifies URL query parameter name to extract JWT token.

4384

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

4385

# Only applies to "in" header type. Must be empty for "in" query type.

4386

# If not empty, the header value has to match (case sensitive) this prefix.

4387

# If not matched, JWT will not be extracted. If matched, JWT will be

4388

# extracted after the prefix is removed.

4389

#

4390

# For example, for "Authorization: Bearer {JWT}",

4391

# value_prefix="Bearer " with a space at the end.

4392

"header": "A String", # Specifies HTTP header name to extract JWT token.

4393

},

4394

],

4395

"audiences": "A String", # The list of JWT

4396

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4397

# that are allowed to access. A JWT containing any of these audiences will

4398

# be accepted. When this setting is absent, JWTs with audiences:

4399

# - "https://[service.name]/[google.protobuf.Api.name]"

4400

# - "https://[service.name]/"

4401

# will be accepted.

4402

# For example, if no audiences are in the setting, LibraryService API will

4403

# accept JWTs with the following audiences:

4404

# -

4405

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

4406

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4411

# bookstore_web.apps.googleusercontent.com

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4412

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4413

# [OpenID

4414

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4415

# Optional if the key set document:

4416

# - can be retrieved from

4417

# [OpenID

4418

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

4419

# the issuer.

4420

# - can be inferred from the email domain of the issuer (e.g. a Google

4421

# service account).

4422

#

4423

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4424

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4425

# `AuthRequirement.provider_id`.

4426

#

4427

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4428

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

4429

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4430

"issuer": "A String", # Identifies the principal that issued the JWT. See

4431

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4432

# Usually a URL or an email address.

4433

#

4434

# Example: https://securetoken.google.com

4435

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4440

"rules": [ # A list of usage rules that apply to individual API methods.

4441

#

4442

# **NOTE:** All service configuration rules follow "last one wins" order.

4443

{ # Usage configuration rules for the service.

4444

#

4445

# NOTE: Under development.

4446

#

4447

#

4448

# Use this rule to configure unregistered calls for the service. Unregistered

4449

# calls are calls that do not contain consumer project identity.

4450

# (Example: calls that do not contain an API key).

4451

# By default, API methods do not allow unregistered calls, and each method call

4452

# must be identified by a consumer project identity. Use this rule to

4453

# allow/disallow unregistered calls.

4454

#

4455

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4461

#

4462

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4467

# allow_unregistered_calls: true

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4468

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4469

# methods in all APIs.

4470

#

4471

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4472

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

4473

# plane features, such as quota and billing, will not be available.

4474

# This flag is used by Google Cloud Endpoints to bypass checks for internal

4475

# methods, such as service health check methods.

4476

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

4477

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4478

},

4479

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4480

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

4481

#

4482

#

4483

# Use this field to configure per-product per-project service identity.

4484

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

4489

# display_name: "Cloud XXX Service Agent"

4490

# description: "Used as the identity of Cloud XXX to access resources"

4491

"displayName": "A String", # Optional. A user-specified name for the service account.

4492

# Must be less than or equal to 100 UTF-8 bytes.

4493

"description": "A String", # Optional. A user-specified opaque description of the service account.

4494

# Must be less than or equal to 256 UTF-8 bytes.

4495

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

4496

#

4497

# An example name would be:

4498

# `projects/123456789`

4499

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4500

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4501

# service producer.

4502

#

4503

# Google Service Management currently only supports

4504

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

4505

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

4506

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

4507

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4508

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4509

# service. Each requirement is of the form <service.name>/<requirement-id>;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4510

# for example 'serviceusage.googleapis.com/billing-enabled'.

4511

"A String",

4512

],

4513

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4514

"configVersion": 42, # The semantic version of the service configuration. The config version

4515

# affects the interpretation of the service configuration. For example,

4516

# certain features are enabled by default for certain config versions.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4517

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4518

# The latest config version is `3`.

4519

"producerProjectId": "A String", # The Google project that owns this service.

4520

"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]

4521

# HttpRule, each specifying the mapping of an RPC method

4522

# to one or more HTTP REST API methods.

4523

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4524

#

4525

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4526

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4527

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4528

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

4529

# more HTTP REST endpoints. It allows developers to build a single API service

4530

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

4531

# APIs](https://github.com/googleapis/googleapis),

4532

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

4533

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

4534

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

4535

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4536

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4537

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

4538

# how different portions of the gRPC request message are mapped to the URL

4539

# path, URL query parameters, and HTTP request body. It also controls how the

4540

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

4541

# typically specified as an `google.api.http` annotation on the gRPC method.

4542

#

4543

# Each mapping specifies a URL path template and an HTTP method. The path

4544

# template may refer to one or more fields in the gRPC request message, as long

4545

# as each field is a non-repeated field with a primitive (non-message) type.

4546

# The path template controls how fields of the request message are mapped to

4547

# the URL path.

4548

#

4549

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4550

#

4551

# service Messaging {

4552

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4553

# option (google.api.http) = {

4554

# get: "/v1/{name=messages/*}"

4555

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4556

# }

4557

# }

4558

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4559

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4560

# }

4561

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4562

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4563

# }

4564

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4565

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4566

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4567

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4568

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4569

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4570

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4571

# Any fields in the request message which are not bound by the path template

4572

# automatically become HTTP query parameters if there is no HTTP request body.

4573

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4574

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4575

# service Messaging {

4576

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4577

# option (google.api.http) = {

4578

# get:"/v1/messages/{message_id}"

4579

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4580

# }

4581

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4582

# message GetMessageRequest {

4583

# message SubMessage {

4584

# string subfield = 1;

4585

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4586

# string message_id = 1; // Mapped to URL path.

4587

# int64 revision = 2; // Mapped to URL query parameter `revision`.

4588

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4589

# }

4590

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4591

# This enables a HTTP JSON to RPC mapping as below:

4592

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4593

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4594

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4595

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4596

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

4597

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4598

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4599

# Note that fields which are mapped to URL query parameters must have a

4600

# primitive type or a repeated primitive type or a non-repeated message type.

4601

# 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^]

4602

# 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]

4603

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4604

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4605

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4606

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4607

# specifies the mapping. Consider a REST update method on the

4608

# message resource collection:

4609

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4610

# service Messaging {

4611

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4612

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4613

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4619

# string message_id = 1; // mapped to the URL

4620

# Message message = 2; // mapped to the body

4621

# }

4622

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4623

# The following HTTP JSON to RPC mapping is enabled, where the

4624

# representation of the JSON in the request body is determined by

4625

# protos JSON encoding:

4626

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4627

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4628

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4629

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4630

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4631

#

4632

# The special name `*` can be used in the body mapping to define that

4633

# every field not bound by the path template should be mapped to the

4634

# request body. This enables the following alternative definition of

4635

# the update method:

4636

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4637

# service Messaging {

4638

# rpc UpdateMessage(Message) returns (Message) {

4639

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4640

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

4647

# string text = 2;

4648

# }

4649

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4650

#

4651

# The following HTTP JSON to RPC mapping is enabled:

4652

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4653

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4654

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4655

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4656

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4657

#

4658

# Note that when using `*` in the body mapping, it is not possible to

4659

# 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]

4660

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4661

# defining REST APIs. The common usage of `*` is in custom methods

4662

# which don't use the URL at all for transferring data.

4663

#

4664

# It is possible to define multiple HTTP methods for one RPC by using

4665

# the `additional_bindings` option. Example:

4666

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4667

# service Messaging {

4668

# rpc GetMessage(GetMessageRequest) returns (Message) {

4669

# option (google.api.http) = {

4670

# get: "/v1/messages/{message_id}"

4671

# additional_bindings {

4672

# get: "/v1/users/{user_id}/messages/{message_id}"

4673

# }

4674

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4675

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4676

# }

4677

# message GetMessageRequest {

4678

# string message_id = 1;

4679

# string user_id = 2;

4680

# }

4681

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4682

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4683

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4684

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4685

# -----|-----

4686

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4687

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

4688

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4689

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4690

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4691

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4692

# 1. Leaf request fields (recursive expansion nested messages in the request

4693

# message) are classified into three categories:

4694

# - Fields referred by the path template. They are passed via the URL path.

4695

# - Fields referred by the HttpRule.body. They are passed via the HTTP

4696

# request body.

4697

# - All other fields are passed via the URL query parameters, and the

4698

# parameter name is the field path in the request message. A repeated

4699

# field can be represented as multiple query parameters under the same

4700

# name.

4701

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

4702

# are passed via URL path and HTTP request body.

4703

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

4704

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4705

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4706

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4707

#

4708

# Template = "/" Segments [ Verb ] ;

4709

# Segments = Segment { "/" Segment } ;

4710

# Segment = "*" | "**" | LITERAL | Variable ;

4711

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4712

# FieldPath = IDENT { "." IDENT } ;

4713

# Verb = ":" LITERAL ;

4714

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4715

# The syntax `*` matches a single URL path segment. The syntax `**` matches

4716

# zero or more URL path segments, which must be the last part of the URL path

4717

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4718

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4719

# The syntax `Variable` matches part of the URL path as specified by its

4720

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4721

# matches a single path segment, its template may be omitted, e.g. `{var}`

4722

# is equivalent to `{var=*}`.

4723

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4724

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

4725

# contains any reserved character, such characters should be percent-encoded

4726

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4727

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4728

# If a variable contains exactly one path segment, such as `"{var}"` or

4729

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

4730

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

4731

# server side does the reverse decoding. Such variables show up in the

4732

# [Discovery

4733

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4734

# `{var}`.

4735

#

4736

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

4737

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

4738

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

4739

# The server side does the reverse decoding, except "%2F" and "%2f" are left

4740

# unchanged. Such variables show up in the

4741

# [Discovery

4742

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4743

# `{+var}`.

4744

#

4745

# ## Using gRPC API Service Configuration

4746

#

4747

# gRPC API Service Configuration (service config) is a configuration language

4748

# for configuring a gRPC service to become a user-facing product. The

4749

# service config is simply the YAML representation of the `google.api.Service`

4750

# proto message.

4751

#

4752

# As an alternative to annotating your proto file, you can configure gRPC

4753

# transcoding in your service config YAML files. You do this by specifying a

4754

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

4755

# effect as the proto annotation. This can be particularly useful if you

4756

# have a proto that is reused in multiple services. Note that any transcoding

4757

# specified in the service config will override any matching transcoding

4758

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

4765

# - selector: example.v1.Messaging.GetMessage

4766

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

4771

# proto to JSON conversion must follow the [proto3

4772

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

4773

#

4774

# While the single segment variable follows the semantics of

4775

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4776

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

4777

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

4778

# does not expand special characters like `?` and `#`, which would lead

4779

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

4780

# for multi segment variables.

4781

#

4782

# The path variables **must not** refer to any repeated or mapped field,

4783

# because client libraries are not capable of handling such variable expansion.

4784

#

4785

# The path variables **must not** capture the leading "/" character. The reason

4786

# is that the most common use case "{var}" does not capture the leading "/"

4787

# character. For consistency, all path variables must share the same behavior.

4788

#

4789

# Repeated message fields must not be mapped to URL query parameters, because

4790

# no client library can support such complicated mapping.

4791

#

4792

# If an API needs to use a JSON array for request or response body, it can map

4793

# the request or response body to a repeated field. However, some gRPC

4794

# Transcoding implementations may not support this feature.

4795

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

4796

# body, or `*` for mapping all request fields not captured by the path

4797

# pattern to the HTTP body, or omitted for not having any HTTP request body.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4798

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4799

# NOTE: the referred field must be present at the top-level of the request

4800

# message type.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4801

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

4802

# resources.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4803

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4804

# not contain an `additional_bindings` field themselves (that is,

4805

# the nesting may only be one level deep).

4806

# Object with schema name: HttpRule

4807

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4808

"selector": "A String", # Selects a method to which this rule applies.

4809

#

4810

# Refer to selector for syntax details.

4811

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

4812

# response body. When omitted, the entire response message will be used

4813

# as the HTTP response body.

4814

#

4815

# NOTE: The referred field must be present at the top-level of the response

4816

# message type.

4817

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

4818

# half-duplex streaming method.

4819

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4820

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4821

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4822

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

4823

# included in the `pattern` field, such as HEAD, or "*" to leave the

4824

# HTTP method unspecified for this rule. The wild-card rule is useful

4825

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4826

"path": "A String", # The path matched by this custom verb.

4827

"kind": "A String", # The name of this custom HTTP verb.

4828

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4829

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4830

},

4831

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4832

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4833

# cases of single segment matches in reserved expansion, where "%2F" will be

4834

# left encoded.

4835

#

4836

# The default behavior is to not decode RFC 6570 reserved characters in multi

4837

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4838

},

4839

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4840

# of the google.protobuf.Api needs to be provided by the configuration

4841

# author, as the remaining fields will be derived from the IDL during the

4842

# normalization process. It is an error to specify an API interface here

4843

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4844

{ # Api is a light-weight descriptor for an API Interface.

4845

#

4846

# Interfaces are also described as "protocol buffer services" in some contexts,

4847

# such as by the "service" keyword in a .proto file, but they are different

4848

# from API Services, which represent a concrete implementation of an interface

4849

# as opposed to simply a description of methods and bindings. They are also

4850

# sometimes simply referred to as "APIs" in other contexts, such as the name of

4851

# this message itself. See https://cloud.google.com/apis/design/glossary for

4852

# detailed terminology.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4853

"name": "A String", # The fully qualified name of this interface, including package name

4854

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4855

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4856

# message.

4857

# protobuf element, like the file in which it is defined.

4858

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4859

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4860

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4861

"mixins": [ # Included interfaces. See Mixin.

4862

{ # Declares an API Interface to be included in this interface. The including

4863

# interface must redeclare all the methods from the included interface, but

4864

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4865

#

4866

# - If after comment and whitespace stripping, the documentation

4867

# string of the redeclared method is empty, it will be inherited

4868

# from the original method.

4869

#

4870

# - Each annotation belonging to the service config (http,

4871

# visibility) which is not set in the redeclared method will be

4872

# inherited.

4873

#

4874

# - If an http annotation is inherited, the path pattern will be

4875

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4876

# version of the including interface plus the root path if

4877

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4878

#

4879

# Example of a simple mixin:

4880

#

4881

# package google.acl.v1;

4882

# service AccessControl {

4883

# // Get the underlying ACL object.

4884

# rpc GetAcl(GetAclRequest) returns (Acl) {

4885

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4890

# service Storage {

4891

# // rpc GetAcl(GetAclRequest) returns (Acl);

4892

#

4893

# // Get a data record.

4894

# rpc GetData(GetDataRequest) returns (Data) {

4895

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4900

#

4901

# apis:

4902

# - name: google.storage.v2.Storage

4903

# mixins:

4904

# - name: google.acl.v1.AccessControl

4905

#

4906

# The mixin construct implies that all methods in `AccessControl` are

4907

# also declared with same name and request/response types in

4908

# `Storage`. A documentation generator or annotation processor will

4909

# see the effective `Storage.GetAcl` method after inherting

4910

# documentation and annotations as follows:

4911

#

4912

# service Storage {

4913

# // Get the underlying ACL object.

4914

# rpc GetAcl(GetAclRequest) returns (Acl) {

4915

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4921

#

4922

# If the `root` field in the mixin is specified, it should be a

4923

# relative path under which inherited HTTP paths are placed. Example:

4924

#

4925

# apis:

4926

# - name: google.storage.v2.Storage

4927

# mixins:

4928

# - name: google.acl.v1.AccessControl

4929

# root: acls

4930

#

4931

# This implies the following inherited HTTP annotation:

4932

#

4933

# service Storage {

4934

# // Get the underlying ACL object.

4935

# rpc GetAcl(GetAclRequest) returns (Acl) {

4936

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4941

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4942

"name": "A String", # The fully qualified name of the interface which is included.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4943

},

4944

],

4945

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4946

"version": "A String", # A version string for this interface. If specified, must have the form

4947

# `major-version.minor-version`, as in `1.10`. If the minor version is

4948

# omitted, it defaults to zero. If the entire version field is empty, the

4949

# major version is derived from the package name, as outlined below. If the

4950

# field is not empty, the version in the package name will be verified to be

4951

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4952

#

4953

# The versioning schema uses [semantic

4954

# versioning](http://semver.org) where the major version number

4955

# indicates a breaking change and the minor version an additive,

4956

# non-breaking change. Both version numbers are signals to users

4957

# what to expect from different versions, and should be carefully

4958

# chosen based on the product plan.

4959

#

4960

# The major version is also reflected in the package name of the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4961

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4962

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4963

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4964

# experimental, non-GA interfaces.

4965

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4966

{ # A protocol buffer option, which can be attached to a message, field,

4967

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4968

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4969

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4970

# For custom options, it should be the fully-qualified name. For example,

4971

# `"google.api.http"`.

4972

"value": { # The option's value packed in an Any message. If the value is a primitive,

4973

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4974

# should be used. If the value is an enum, it should be stored as an int32

4975

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4976

"a_key": "", # Properties of the object. Contains field @type with type URL.

4977

},

4978

},

4979

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

4980

"methods": [ # The methods of this interface, in unspecified order.

4981

{ # Method represents a method of an API interface.

4982

"name": "A String", # The simple name of this method.

4983

"requestStreaming": True or False, # If true, the request is streamed.

4984

"responseTypeUrl": "A String", # The URL of the output message type.

4985

"requestTypeUrl": "A String", # A URL of the input message type.

4986

"responseStreaming": True or False, # If true, the response is streamed.

4987

"syntax": "A String", # The source syntax of this method.

4988

"options": [ # Any metadata attached to the method.

4989

{ # A protocol buffer option, which can be attached to a message, field,

4990

# enumeration, etc.

4991

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4992

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4993

# For custom options, it should be the fully-qualified name. For example,

4994

# `"google.api.http"`.

4995

"value": { # The option's value packed in an Any message. If the value is a primitive,

4996

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4997

# should be used. If the value is an enum, it should be stored as an int32

4998

# value using the google.protobuf.Int32Value type.

4999

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5005

},

5006

],

5007

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5008

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5016

# - google.foo.v1.AnotherError

5017

"rules": [ # The list of custom error rules that apply to individual API messages.

5018

#

5019

# **NOTE:** All service configuration rules follow "last one wins" order.

5020

{ # A custom error rule.

5021

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5022

# objects of this type will be filtered when they appear in error payload.

5023

"selector": "A String", # Selects messages to which this rule applies.

5024

#

5025

# Refer to selector for syntax details.

5026

},

5027

],

5028

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

5029

"A String",

5030

],

5031

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5032

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

5033

# usage.

5034

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5035

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5036

# - The service configuration defines a set of metrics.

5037

# - For API calls, the quota.metric_rules maps methods to metrics with

5038

# corresponding costs.

5039

# - The quota.limits defines limits on the metrics, which will be used for

5040

# quota checks at runtime.

5041

#

5042

# An example quota configuration in yaml format:

5043

#

5044

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5045

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5046

#

5047

# - name: apiWriteQpsPerProject

5048

# metric: library.googleapis.com/write_calls

5049

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

5055

# # except for the UpdateBook and DeleteBook methods. These two methods

5056

# # are mapped to the write_calls metric, with the UpdateBook method

5057

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

5062

# - selector: google.example.library.v1.LibraryService.UpdateBook

5063

# metric_costs:

5064

# library.googleapis.com/write_calls: 2

5065

# - selector: google.example.library.v1.LibraryService.DeleteBook

5066

# metric_costs:

5067

# library.googleapis.com/write_calls: 1

5068

#

5069

# Corresponding Metric definition:

5070

#

5071

# metrics:

5072

# - name: library.googleapis.com/read_calls

5073

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

5078

# display_name: Write requests

5079

# metric_kind: DELTA

5080

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5081

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5082

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

5083

# or more metrics.

5084

{ # Bind API methods to metrics. Binding a method to a metric causes that

5085

# metric's configured quota behaviors to apply to the method call.

5086

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

5087

# cost applied to each metric.

5088

#

5089

# The key of the map is the metric name, and the values are the amount

5090

# increased for the metric against which the quota limits are defined.

5091

# The value must not be negative.

5092

"a_key": "A String",

5093

},

5094

"selector": "A String", # Selects the methods to which this rule applies.

5095

#

5096

# Refer to selector for syntax details.

5097

},

5098

],

5099

"limits": [ # List of `QuotaLimit` definitions for the service.

5100

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

5101

# for a limit type. There can be at most one limit for a duration and limit

5102

# type combination defined within a `QuotaGroup`.

5103

"displayName": "A String", # User-visible display name for this limit.

5104

# Optional. If not set, the UI will provide a default display name based on

5105

# the quota configuration. This field can be used to override the default

5106

# display name generated from the configuration.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5107

"description": "A String", # Optional. User-visible, extended description for this quota limit.

5108

# Should be used only when more context is needed to understand this limit

5109

# than provided by the limit's display name (see: `display_name`).

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5110

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

5111

# duration. This is the number of tokens assigned when a client

5112

# application developer activates the service for his/her project.

5113

#

5114

# Specifying a value of 0 will block all requests. This can be used if you

5115

# are provisioning quota to selected consumers and blocking others.

5116

# Similarly, a value of -1 will indicate an unlimited quota. No other

5117

# negative values are allowed.

5118

#

5119

# Used by group-based quotas only.

5120

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

5121

# the same metric will be checked together during runtime. The metric must be

5122

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5123

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

5124

# integer value that is the maximum number of requests allowed for the

5125

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5126

"a_key": "A String",

5127

},

5128

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

5129

# duration. Client application developers can override the default limit up

5130

# to this maximum. If specified, this value cannot be set to a value less

5131

# than the default limit. If not specified, it is set to the default limit.

5132

#

5133

# To allow clients to apply overrides with no upper bound, set this to -1,

5134

# indicating unlimited maximum quota.

5135

#

5136

# Used by group-based quotas only.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5137

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5138

#

5139

# Used by group-based quotas only.

5140

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

5141

# The free tier is the number of tokens that will be subtracted from the

5142

# billed amount when billing is enabled.

5143

# This field can only be set on a limit with duration "1d", in a billable

5144

# group; it is invalid on any other limit. If this field is not set, it

5145

# defaults to 0, indicating that there is no free tier for this service.

5146

#

5147

# Used by group-based quotas only.

5148

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

5149

# Metric.unit. The supported unit kinds are determined by the quota

5150

# backend system.

5151

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5152

# Here are some examples:

5153

# * "1/min/{project}" for quota per minute per project.

5154

#

5155

# Note: the order of unit components is insignificant.

5156

# The "1" at the beginning is required to follow the metric unit syntax.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5157

"name": "A String", # Name of the quota limit.

5158

#

5159

# The name must be provided, and it must be unique within the service. The

5160

# name can only include alphanumeric characters as well as '-'.

5161

#

5162

# The maximum length of the limit name is 64 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5167

{ # Defines a metric type and its schema. Once a metric descriptor is created,

5168

# deleting or altering it stops data collection and makes the metric type's

5169

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5170

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5171

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5172

# This field is optional but it is recommended to be set for any metrics

5173

# associated with user-visible concepts, such as Quota.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5174

"description": "A String", # A detailed description of the metric, which can be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5175

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5176

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5177

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5178

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5179

"labels": [ # The set of labels that can be used to describe a specific

5180

# instance of this metric type. For example, the

5181

# `appengine.googleapis.com/http/server/response_latencies` metric

5182

# type has a label for the HTTP response code, `response_code`, so

5183

# you can look at latencies for successful responses or just

5184

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5185

{ # A description of a label.

5186

"valueType": "A String", # The type of data that can be assigned to the label.

5187

"description": "A String", # A human-readable description for the label.

5188

"key": "A String", # The label key.

5189

},

5190

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5191

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5192

"monitoredResourceTypes": [ # Read-only. If present, then a time

5193

# series, which is identified partially by

5194

# a metric type and a MonitoredResourceDescriptor, that is associated

5195

# with this metric type can only be associated with one of the monitored

5196

# resource types listed here.

5197

"A String",

5198

],

5199

"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.

5200

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

5201

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

5202

# age are guaranteed to be ingested and available to be read, excluding

5203

# data loss due to errors.

5204

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

5205

# periodically, consecutive data points are stored at this time interval,

5206

# excluding data loss due to errors. Metrics with a higher granularity have

5207

# a smaller sampling period.

5208

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5209

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5210

# URL-encoded. All user-defined metric types have the DNS name

5211

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

5212

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5213

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5214

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5215

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5216

# "appengine.googleapis.com/http/server/response_latencies"

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5217

"unit": "A String", # The units in which the metric value is reported. It is only applicable

5218

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

5219

# defines the representation of the stored metric values.

5220

#

5221

# Different systems may scale the values to be more easily displayed (so a

5222

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

5223

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

5224

# `KBy`, then the value of the metric is always in thousands of bytes, no

5225

# matter how it may be displayed..

5226

#

5227

# If you want a custom metric to record the exact number of CPU-seconds used

5228

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

5229

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

5230

# CPU-seconds, then the value is written as `12005`.

5231

#

5232

# Alternatively, if you want a custom metric to record data in a more

5233

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

5234

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

5235

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

5236

#

5237

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5238

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5239

#

5240

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

5250

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

5258

# * `Y` yotta (10^24)

5259

#

5260

# * `m` milli (10^-3)

5261

# * `u` micro (10^-6)

5262

# * `n` nano (10^-9)

5263

# * `p` pico (10^-12)

5264

# * `f` femto (10^-15)

5265

# * `a` atto (10^-18)

5266

# * `z` zepto (10^-21)

5267

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5274

#

5275

# **Grammar**

5276

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5277

# The grammar also includes these connectors:

5278

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5279

# * `/` division or ratio (as an infix operator). For examples,

5280

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

5281

# have `/s` in a metric `unit`; rates should always be computed at

5282

# query time from the underlying cumulative or delta value).

5283

# * `.` multiplication or composition (as an infix operator). For

5284

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5285

#

5286

# The grammar for a unit is as follows:

5287

#

5288

# Expression = Component { "." Component } { "/" Component } ;

5289

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5290

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

5296

#

5297

# Notes:

5298

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5299

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

5300

# is used alone, then the unit is equivalent to `1`. For examples,

5301

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5302

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5303

# containing `{` or `}`.

5304

# * `1` represents a unitary [dimensionless

5305

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

5306

# as in `1/s`. It is typically used when none of the basic units are

5307

# appropriate. For example, "new users per day" can be represented as

5308

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

5309

# users). Alternatively, "thousands of page views per day" would be

5310

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

5311

# value of `5.3` would mean "5300 page views per day").

5312

# * `%` represents dimensionless value of 1/100, and annotates values giving

5313

# a percentage (so the metric values are typically in the range of 0..100,

5314

# and a metric value `3` means "3 percent").

5315

# * `10^2.%` indicates a metric contains a ratio, typically in the range

5316

# 0..1, that will be multiplied by 100 and displayed as a percentage

5317

# (so a metric value `0.03` means "3 percent").

5318

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5319

},

5320

],

5321

"enums": [ # A list of all enum types included in this API service. Enums

5322

# referenced directly or indirectly by the `apis` are automatically

5323

# included. Enums which are not referenced but shall be included

5324

# should be listed here by name. Example:

5325

#

5326

# enums:

5327

# - name: google.someapi.v1.SomeEnum

5328

{ # Enum type definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5329

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5330

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5331

# protobuf element, like the file in which it is defined.

5332

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5333

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5334

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5335

"options": [ # Protocol buffer options.

5336

{ # A protocol buffer option, which can be attached to a message, field,

5337

# enumeration, etc.

5338

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5339

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5340

# For custom options, it should be the fully-qualified name. For example,

5341

# `"google.api.http"`.

5342

"value": { # The option's value packed in an Any message. If the value is a primitive,

5343

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5344

# should be used. If the value is an enum, it should be stored as an int32

5345

# value using the google.protobuf.Int32Value type.

5346

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5351

"enumvalue": [ # Enum value definitions.

5352

{ # Enum value definition.

5353

"options": [ # Protocol buffer options.

5354

{ # A protocol buffer option, which can be attached to a message, field,

5355

# enumeration, etc.

5356

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5357

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5358

# For custom options, it should be the fully-qualified name. For example,

5359

# `"google.api.http"`.

5360

"value": { # The option's value packed in an Any message. If the value is a primitive,

5361

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5362

# should be used. If the value is an enum, it should be stored as an int32

5363

# value using the google.protobuf.Int32Value type.

5364

"a_key": "", # Properties of the object. Contains field @type with type URL.

5365

},

5366

},

5367

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5368

"number": 42, # Enum value number.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5369

"name": "A String", # Enum value name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5370

},

5371

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5372

},

5373

],

5374

"types": [ # A list of all proto message types included in this API service.

5375

# Types referenced directly or indirectly by the `apis` are

5376

# automatically included. Messages which are not referenced but

5377

# shall be included, such as types used by the `google.protobuf.Any` type,

5378

# should be listed here by name. Example:

5379

#

5380

# types:

5381

# - name: google.protobuf.Int32

5382

{ # A protocol buffer message type.

5383

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5384

"A String",

5385

],

5386

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5387

"fields": [ # The list of fields.

5388

{ # A single field of a message type.

5389

"kind": "A String", # The field type.

5390

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5391

# types. The first type has index 1; zero means the type is not in the list.

5392

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5393

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5394

"name": "A String", # The field name.

5395

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5396

"jsonName": "A String", # The field JSON name.

5397

"number": 42, # The field number.

5398

"cardinality": "A String", # The field cardinality.

5399

"options": [ # The protocol buffer options.

5400

{ # A protocol buffer option, which can be attached to a message, field,

5401

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5402

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5403

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5404

# For custom options, it should be the fully-qualified name. For example,

5405

# `"google.api.http"`.

5406

"value": { # The option's value packed in an Any message. If the value is a primitive,

5407

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5408

# should be used. If the value is an enum, it should be stored as an int32

5409

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5410

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5415

},

5416

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5417

"syntax": "A String", # The source syntax.

5418

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5419

# protobuf element, like the file in which it is defined.

5420

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5421

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5422

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5423

"options": [ # The protocol buffer options.

5424

{ # A protocol buffer option, which can be attached to a message, field,

5425

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5426

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5427

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5428

# For custom options, it should be the fully-qualified name. For example,

5429

# `"google.api.http"`.

5430

"value": { # The option's value packed in an Any message. If the value is a primitive,

5431

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5432

# should be used. If the value is an enum, it should be stored as an int32

5433

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5434

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5440

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5441

#

5442

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5443

# producer and consumer projects. In the example, the `activity_history`

5444

# log is sent to both the producer and consumer projects, whereas the

5445

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5446

#

5447

# monitored_resources:

5448

# - type: library.googleapis.com/branch

5449

# labels:

5450

# - key: /city

5451

# description: The city where the library branch is located in.

5452

# - key: /name

5453

# description: The name of the branch.

5454

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5455

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5456

# labels:

5457

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5458

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5459

# logging:

5460

# producer_destinations:

5461

# - monitored_resource: library.googleapis.com/branch

5462

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5463

# - activity_history

5464

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5465

# consumer_destinations:

5466

# - monitored_resource: library.googleapis.com/branch

5467

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5468

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5469

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5470

# There can be multiple producer destinations, each one must have a

5471

# different monitored resource type. A log can be used in at most

5472

# one producer destination.

5473

{ # Configuration of a specific logging destination (the producer project

5474

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5475

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5476

# Service.monitored_resources section.

5477

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5478

# be defined in the Service.logs section. If the log name is

5479

# not a domain scoped name, it will be automatically prefixed with

5480

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5486

# There can be multiple consumer destinations, each one must have a

5487

# different monitored resource type. A log can be used in at most

5488

# one consumer destination.

5489

{ # Configuration of a specific logging destination (the producer project

5490

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5491

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5492

# Service.monitored_resources section.

5493

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5494

# be defined in the Service.logs section. If the log name is

5495

# not a domain scoped name, it will be automatically prefixed with

5496

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5502

"name": "A String", # The service name, which is a DNS-like logical identifier for the

5503

# service, such as `calendar.googleapis.com`. The service name

5504

# typically goes through DNS verification to make sure the owner

5505

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5506

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5507

#

5508

# Example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5509

# <pre><code>documentation:

5510

# summary: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5511

# The Google Calendar API gives access

5512

# to most calendar features.

5513

# pages:

5514

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5515

# content: &#40;== include google/foo/overview.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5516

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5517

# content: &#40;== include google/foo/tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5518

# subpages;

5519

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5520

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5521

# rules:

5522

# - selector: google.calendar.Calendar.Get

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5523

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5524

# ...

5525

# - selector: google.calendar.Calendar.Put

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5526

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5527

# ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5528

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5529

# Documentation is provided in markdown syntax. In addition to

5530

# standard markdown features, definition lists, tables and fenced

5531

# code blocks are supported. Section headers can be provided and are

5532

# interpreted relative to the section nesting of the context where

5533

# a documentation fragment is embedded.

5534

#

5535

# Documentation from the IDL is merged with documentation defined

5536

# via the config at normalization time, where documentation provided

5537

# by config rules overrides IDL provided.

5538

#

5539

# A number of constructs specific to the API platform are supported

5540

# in documentation text.

5541

#

5542

# In order to reference a proto element, the following

5543

# notation can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5544

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5545

# To override the display text used for the link, this can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5546

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5547

# Text can be excluded from doc using the following notation:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5548

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5549

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5550

# A few directives are available in documentation. Note that

5551

# directives must appear on a single line to be properly

5552

# identified. The `include` directive includes a markdown file from

5553

# an external source:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5554

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5555

# The `resource_for` directive marks a message to be the resource of

5556

# a collection in REST view. If it is not specified, tools attempt

5557

# to infer the resource from the operations in a collection:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5558

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5559

# The directive `suppress_warning` does not directly affect documentation

5560

# and is documented together with service config validation.

5561

"rules": [ # A list of documentation rules that apply to individual API elements.

5562

#

5563

# **NOTE:** All service configuration rules follow "last one wins" order.

5564

{ # A documentation rule provides information about individual API elements.

5565

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5566

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

5567

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5568

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5569

# qualified name of the element which may end in "*", indicating a wildcard.

5570

# Wildcards are only allowed at the end and for a whole component of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5571

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

5572

# wildcard will match one or more components. To specify a default for all

5573

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5574

},

5575

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5576

"documentationRootUrl": "A String", # The URL to the root of documentation.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5577

"summary": "A String", # A short summary of what the service does. Can only be provided by

5578

# plain text.

5579

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

5580

# from the yaml file) is not suitable. This can be seen in any fully

5581

# specified service urls as well as sections that show a base that other

5582

# urls are relative to.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5583

"overview": "A String", # Declares a single overview page. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5584

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5585

# summary: ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5586

# overview: &#40;== include overview.md ==&#41;

5587

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5588

# This is a shortcut for the following declaration (using pages style):

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5589

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5590

# summary: ...

5591

# pages:

5592

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5593

# content: &#40;== include overview.md ==&#41;

5594

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5595

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5596

"pages": [ # The top level pages for the documentation set.

5597

{ # Represents a documentation page. A page can contain subpages to represent

5598

# nested documentation set structure.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5599

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

5600

# ==&#41;</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5601

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5602

# honored in the generated docset.

5603

# Object with schema name: Page

5604

],

5605

"name": "A String", # The name of the page. It will be used as an identity of the page to

5606

# generate URI of the page, text of the link to this page in navigation,

5607

# etc. The full page name (start from the root page name to this page

5608

# concatenated with `.`) can be used as reference to the page in your

5609

# documentation. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5610

# <pre><code>pages:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5611

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5612

# content: &#40;== include tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5613

# subpages:

5614

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5615

# content: &#40;== include tutorial_java.md ==&#41;

5616

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5617

# You can reference `Java` page using Markdown reference link syntax:

5618

# `Java`.

5619

},

5620

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5621

},

5622

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

5623

"sourceFiles": [ # All files used during config generation.

5624

{

5625

"a_key": "", # Properties of the object. Contains field @type with type URL.

5626

},

5627

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5628

},

5629

"systemTypes": [ # A list of all proto message types included in this API service.

5630

# It serves similar purpose as [google.api.Service.types], except that

5631

# these types are not needed by user-defined APIs. Therefore, they will not

5632

# show up in the generated discovery doc. This field should only be used

5633

# to define system APIs in ESF.

5634

{ # A protocol buffer message type.

5635

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5636

"A String",

5637

],

5638

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5639

"fields": [ # The list of fields.

5640

{ # A single field of a message type.

5641

"kind": "A String", # The field type.

5642

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5643

# types. The first type has index 1; zero means the type is not in the list.

5644

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5645

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5646

"name": "A String", # The field name.

5647

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5648

"jsonName": "A String", # The field JSON name.

5649

"number": 42, # The field number.

5650

"cardinality": "A String", # The field cardinality.

5651

"options": [ # The protocol buffer options.

5652

{ # A protocol buffer option, which can be attached to a message, field,

5653

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5654

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5655

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5656

# For custom options, it should be the fully-qualified name. For example,

5657

# `"google.api.http"`.

5658

"value": { # The option's value packed in an Any message. If the value is a primitive,

5659

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5660

# should be used. If the value is an enum, it should be stored as an int32

5661

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5662

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5667

},

5668

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5669

"syntax": "A String", # The source syntax.

5670

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5671

# protobuf element, like the file in which it is defined.

5672

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5673

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5674

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5675

"options": [ # The protocol buffer options.

5676

{ # A protocol buffer option, which can be attached to a message, field,

5677

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5678

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5679

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5680

# For custom options, it should be the fully-qualified name. For example,

5681

# `"google.api.http"`.

5682

"value": { # The option's value packed in an Any message. If the value is a primitive,

5683

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5684

# should be used. If the value is an enum, it should be stored as an int32

5685

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5686

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

5701

# - google.rpc.context.OriginContext

5702

#

5703

# The above specifies that all methods in the API request

5704

# `google.rpc.context.ProjectContext` and

5705

# `google.rpc.context.OriginContext`.

5706

#

5707

# Available context types are defined in package

5708

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5709

#

5710

# This also provides mechanism to whitelist any protobuf message extension that

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5711

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

5712

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5713

# 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"

5721

# allowed_request_extensions:

5722

# - google.foo.v1.NewExtension

5723

# allowed_response_extensions:

5724

# - google.foo.v1.NewExtension

5725

#

5726

# You can also specify extension ID instead of fully qualified extension name

5727

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5728

"rules": [ # A list of RPC context rules that apply to individual API methods.

5729

#

5730

# **NOTE:** All service configuration rules follow "last one wins" order.

5731

{ # A context rule provides information about the context for an individual API

5732

# element.

5733

"provided": [ # A list of full type names of provided contexts.

5734

"A String",

5735

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5736

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5737

# side channel from backend to client.

5738

"A String",

5739

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5740

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5741

# side channel from client to backend.

5742

"A String",

5743

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5744

"requested": [ # A list of full type names of requested contexts.

5745

"A String",

5746

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5747

"selector": "A String", # Selects the methods to which this rule applies.

5748

#

5749

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5750

},

5751

],

5752

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5753

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5754

# with the same name as the service is automatically generated to service all

5755

# defined APIs.

5756

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5757

# A service may expose any number of endpoints, and all endpoints share the

5758

# same service configuration, such as quota configuration and monitoring

5759

# configuration.

5760

#

5761

# Example service configuration:

5762

#

5763

# name: library-example.googleapis.com

5764

# endpoints:

5765

# # Below entry makes 'google.example.library.v1.Library'

5766

# # API be served from endpoint address library-example.googleapis.com.

5767

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5768

# # it to decide whether the subsequent cross-origin request is

5769

# # allowed to proceed.

5770

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5771

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5772

"allowCors": True or False, # Allowing

5773

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5774

# cross-domain traffic, would allow the backends served from this endpoint to

5775

# receive and respond to HTTP OPTIONS requests. The response will be used by

5776

# the browser to determine whether the subsequent cross-origin request is

5777

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5778

"target": "A String", # The specification of an Internet routable address of API frontend that will

5779

# handle requests to this [API

5780

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

5781

# either a valid IPv4 address or a fully-qualified domain name. For example,

5782

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5783

"features": [ # The list of features enabled on this endpoint.

5784

"A String",

5785

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5786

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5787

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5788

# please specify multiple google.api.Endpoint for each of the intended

5789

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5790

#

5791

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5800

<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]

5801

<pre>Lists the history of the service configuration for a managed service,

5802

from the newest to the oldest.

5803

5804

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5805

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]

5806

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5807

pageSize: integer, The max number of items to include in the response list. Page size is 50

5808

if not specified. Maximum value is 100.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5809

pageToken: string, The token of the page to retrieve.

5810

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5817

5818

{ # Response message for ListServiceConfigs method.

5819

"nextPageToken": "A String", # The token of the next page of results.

5820

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5821

{ # `Service` is the root object of Google service configuration schema. It

5822

# describes basic information about a service, such as the name and the

5823

# title, and delegates other aspects to sub-sections. Each sub-section is

5824

# either a proto message or a repeated proto message that configures a

5825

# 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]

5830

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5831

# name: calendar.googleapis.com

5832

# title: Google Calendar API

5833

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5834

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5835

# authentication:

5836

# providers:

5837

# - id: google_calendar_auth

5838

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5839

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5840

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5841

# - selector: "*"

5842

# requirements:

5843

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5844

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

5845

# service controller handles features like abuse, quota, billing, logging,

5846

# monitoring, etc.

5847

"environment": "A String", # The service control environment to use. If empty, no control plane

5848

# feature (like quota and billing) will be enabled.

5849

},

5850

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5851

# by the Service.monitoring and Service.logging configurations.

5852

{ # An object that describes the schema of a MonitoredResource object using a

5853

# type name and a set of labels. For example, the monitored resource

5854

# descriptor for Google Compute Engine VM instances has a type of

5855

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5856

# `"zone"` to identify particular VM instances.

5857

#

5858

# Different APIs can support different monitored resource types. APIs generally

5859

# provide a `list` method that returns the monitored resource descriptors used

5860

# by the API.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5861

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5862

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5863

# without any article or other determiners. For example,

5864

# `"Google Cloud SQL Database"`.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5865

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5866

# be used in documentation.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

5867

"labels": [ # Required. A set of labels used to describe instances of this monitored

5868

# resource type. For example, an individual Google Cloud SQL database is

5869

# identified by values for the labels `"database_id"` and `"zone"`.

5870

{ # A description of a label.

5871

"valueType": "A String", # The type of data that can be assigned to the label.

5872

"description": "A String", # A human-readable description for the label.

5873

"key": "A String", # The label key.

5874

},

5875

],

5876

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

5877

"type": "A String", # Required. The monitored resource type. For example, the type

5878

# `"cloudsql_database"` represents databases in Google Cloud SQL.

5879

# The maximum length of this value is 256 characters.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5880

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5881

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5882

# {type} is the value of the `type` field in this object and

5883

# {project_id} is a project ID that provides API-specific context for

5884

# accessing the type. APIs that do not use project information can use the

5885

# resource name format `"monitoredResourceDescriptors/{type}"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5886

},

5887

],

5888

"logs": [ # Defines the logs used by this service.

5889

{ # A description of a log type. Example in YAML format:

5890

#

5891

# - name: library.googleapis.com/activity_history

5892

# description: The history of borrowing and returning library items.

5893

# display_name: Activity

5894

# labels:

5895

# - key: /customer_id

5896

# description: Identifier of a library customer

5897

"labels": [ # The set of labels that are available to describe a specific log entry.

5898

# Runtime requests that contain labels not specified here are

5899

# considered invalid.

5900

{ # A description of a label.

5901

"valueType": "A String", # The type of data that can be assigned to the label.

5902

"description": "A String", # A human-readable description for the label.

5903

"key": "A String", # The label key.

5904

},

5905

],

5906

"displayName": "A String", # The human-readable name for this log. This information appears on

5907

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5908

"name": "A String", # The name of the log. It must be less than 512 characters long and can

5909

# include the following characters: upper- and lower-case alphanumeric

5910

# characters [A-Za-z0-9], and punctuation characters including

5911

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5912

"description": "A String", # A human-readable description of this log. This information appears in

5913

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5914

},

5915

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5916

"systemParameters": { # ### System parameter configuration # System parameter configuration.

5917

#

5918

# A system parameter is a special kind of parameter defined by the API

5919

# system, not by an individual API. It is typically mapped to an HTTP header

5920

# and/or a URL query parameter. This configuration specifies which methods

5921

# change the names of the system parameters.

5922

"rules": [ # Define system parameters.

5923

#

5924

# The parameters defined here will override the default parameters

5925

# implemented by the system. If this field is missing from the service

5926

# config, default system parameters will be used. Default system parameters

5927

# and names is implementation-dependent.

5928

#

5929

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

5937

#

5938

#

5939

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

5944

# parameters:

5945

# - name: api_key

5946

# http_header: Api-Key1

5947

# - name: api_key

5948

# http_header: Api-Key2

5949

#

5950

# **NOTE:** All service configuration rules follow "last one wins" order.

5951

{ # Define a system parameter rule mapping system parameter definitions to

5952

# methods.

5953

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

5954

# For a given method call, only one of them should be used. If multiple

5955

# names are used the behavior is implementation-dependent.

5956

# If none of the specified names are present the behavior is

5957

# parameter-dependent.

5958

{ # Define a parameter's name and location. The parameter may be passed as either

5959

# an HTTP header or a URL query parameter, and if both are passed the behavior

5960

# is implementation-dependent.

5961

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

5962

# sensitive.

5963

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

5964

# insensitive.

5965

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

5966

},

5967

],

5968

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5969

# methods in all APIs.

5970

#

5971

# Refer to selector for syntax details.

5972

},

5973

],

5974

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5975

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

5976

"rules": [ # A list of API backend rules that apply to individual API methods.

5977

#

5978

# **NOTE:** All service configuration rules follow "last one wins" order.

5979

{ # A backend rule provides configuration for an individual API element.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

5980

"jwtAudience": "A String", # The JWT audience is used when generating a JWT ID token for the backend.

5981

# This ID token will be added in the HTTP "authorization" header, and sent

5982

# to the backend.

5983

"protocol": "A String", # The protocol used for sending a request to the backend.

5984

# The supported values are "http/1.1" and "h2".

5985

#

5986

# 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

5996

# to "h2" for improved performance.

5997

#

5998

# Configuring this field to non-default values is only supported for secure

5999

# HTTP backends. This field will be ignored for all other backends.

6000

#

6001

# See

6002

# https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

6003

# for more details on the supported values.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6004

"pathTranslation": "A String",

6005

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

6006

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6007

"selector": "A String", # Selects the methods to which this rule applies.

6008

#

6009

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6010

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

6011

# operation. The default is no deadline.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6012

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

6013

# varies based on the request protocol and deployment environment.

6014

"disableAuth": True or False, # When disable_auth is true, a JWT ID token won't be generated and the

6015

# original "Authorization" HTTP header will be preserved. If the header is

6016

# used to carry the original token and is expected by the backend, this

6017

# field must be set to true to preserve the header.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6018

"address": "A String", # The address of the API backend.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6019

#

6020

# The scheme is used to determine the backend protocol and security.

6021

# The following schemes are accepted:

6022

#

6023

# 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

6030

# may cause constrasting behaviors across platforms.

6031

#

6032

# If the port is unspecified, the default is:

6033

# - 80 for schemes without TLS

6034

# - 443 for schemes with TLS

6035

#

6036

# For HTTP backends, use protocol

6037

# to specify the protocol version.

6038

"renameTo": "A String", # Unimplemented. Do not use.

6039

#

6040

# The new name the selected proto elements should be renamed to.

6041

#

6042

# The package, the service and the method can all be renamed.

6043

# The backend server should implement the renamed proto. However, clients

6044

# should call the original method, and ESF routes the traffic to the renamed

6045

# method.

6046

#

6047

# HTTP clients should call the URL mapped to the original method.

6048

# gRPC and Stubby clients should call the original method with package name.

6049

#

6050

# For legacy reasons, ESF allows Stubby clients to call with the

6051

# short name (without the package name). However, for API Versioning(or

6052

# multiple methods mapped to the same short name), all Stubby clients must

6053

# call the method's full name with the package name, otherwise the first one

6054

# (selector) wins.

6055

#

6056

# If this `rename_to` is specified with a trailing `*`, the `selector` must

6057

# be specified with a trailing `*` as well. The all element short names

6058

# matched by the `*` in the selector will be kept in the `rename_to`.

#

# For example,

# rename_rules:

# - selector: |-

# google.example.library.v1.*

6064

# rename_to: google.example.library.*

6065

#

6066

# The selector matches `google.example.library.v1.Library.CreateShelf` and

6067

# `google.example.library.v1.Library.CreateBook`, they will be renamed to

6068

# `google.example.library.Library.CreateShelf` and

6069

# `google.example.library.Library.CreateBook`. It essentially renames the

6070

# proto package name section of the matched proto service and methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6071

},

6072

],

6073

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6074

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6075

#

6076

# The example below shows how to configure monitored resources and metrics

6077

# for monitoring. In the example, a monitored resource and two metrics are

6078

# defined. The `library.googleapis.com/book/returned_count` metric is sent

6079

# to both producer and consumer projects, whereas the

6080

# `library.googleapis.com/book/overdue_count` metric is only sent to the

6081

# consumer project.

6082

#

6083

# monitored_resources:

6084

# - type: library.googleapis.com/branch

6085

# labels:

6086

# - key: /city

6087

# description: The city where the library branch is located in.

6088

# - key: /name

6089

# description: The name of the branch.

6090

# metrics:

6091

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

6096

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

6101

# monitoring:

6102

# producer_destinations:

6103

# - monitored_resource: library.googleapis.com/branch

6104

# metrics:

6105

# - library.googleapis.com/book/returned_count

6106

# consumer_destinations:

6107

# - monitored_resource: library.googleapis.com/branch

6108

# metrics:

6109

# - library.googleapis.com/book/returned_count

6110

# - library.googleapis.com/book/overdue_count

6111

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6112

# There can be multiple producer destinations. A monitored resouce type may

6113

# appear in multiple monitoring destinations if different aggregations are

6114

# needed for different sets of metrics associated with that monitored

6115

# resource type. A monitored resource and metric pair may only be used once

6116

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6117

{ # Configuration of a specific monitoring destination (the producer project

6118

# or the consumer project).

6119

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6120

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6121

"metrics": [ # Types of the metrics to report to this monitoring destination.

6122

# Each type must be defined in Service.metrics section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6128

# There can be multiple consumer destinations. A monitored resouce type may

6129

# appear in multiple monitoring destinations if different aggregations are

6130

# needed for different sets of metrics associated with that monitored

6131

# resource type. A monitored resource and metric pair may only be used once

6132

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6133

{ # Configuration of a specific monitoring destination (the producer project

6134

# or the consumer project).

6135

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6136

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6137

"metrics": [ # Types of the metrics to report to this monitoring destination.

6138

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

6145

#

6146

# The following example shows how to configure monitored resources and metrics

6147

# for billing:

6148

#

6149

# monitored_resources:

6150

# - type: library.googleapis.com/branch

6151

# labels:

6152

# - key: /city

6153

# description: The city where the library branch is located in.

6154

# - key: /name

6155

# description: The name of the branch.

6156

# metrics:

6157

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

6162

# - monitored_resource: library.googleapis.com/branch

6163

# metrics:

6164

# - library.googleapis.com/book/borrowed_count

6165

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

6166

# There can be multiple consumer destinations per service, each one must have

6167

# a different monitored resource type. A metric can be used in at most

6168

# one consumer destination.

6169

{ # Configuration of a specific billing destination (Currently only support

6170

# bill against consumer project).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6171

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6172

# Each name must be defined in Service.metrics section.

6173

"A String",

6174

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6175

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

6176

# Service.monitored_resources section.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6177

},

6178

],

6179

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6180

"title": "A String", # The product title for this service.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6181

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

6182

# by the client for tracking purpose. Must be no longer than 63 characters

6183

# and only lower case letters, digits, '.', '_' and '-' are allowed. If

6184

# empty, the server may choose to generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6185

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

6186

#

6187

# Example for an API targeted for external use:

6188

#

6189

# name: calendar.googleapis.com

6190

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6191

# providers:

6192

# - id: google_calendar_auth

6193

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

6194

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6195

# rules:

6196

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6197

# requirements:

6198

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6199

"rules": [ # A list of authentication rules that apply to individual API methods.

6200

#

6201

# **NOTE:** All service configuration rules follow "last one wins" order.

6202

{ # Authentication rules for the service.

6203

#

6204

# By default, if a method has any authentication requirements, every request

6205

# must include a valid credential matching one of the requirements.

6206

# It's an error to include more than one kind of credential in a single

6207

# request.

6208

#

6209

# If a method doesn't have any auth requirements, request credentials will be

6210

# ignored.

6211

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

6212

# there are scopes defined for "Read-only access to Google Calendar" and

6213

# "Access to Cloud Platform". Users can consent to a scope for an application,

6214

# giving it permission to access that data on their behalf.

6215

#

6216

# OAuth scope specifications should be fairly coarse grained; a user will need

6217

# to see and understand the text description of what your scope means.

6218

#

6219

# In most cases: use one or at most two OAuth scopes for an entire family of

6220

# products. If your product has multiple APIs, you should probably be sharing

6221

# the OAuth scope across all of those APIs.

6222

#

6223

# When you need finer grained OAuth consent screens: talk with your product

6224

# management about how developers will use them in practice.

6225

#

6226

# Please note that even though each of the canonical scopes is enough for a

6227

# request to be accepted and passed to the backend, a request can still fail

6228

# due to the backend requiring additional scopes or permissions.

6229

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

6230

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

6235

# https://www.googleapis.com/auth/calendar.read

6236

},

6237

"requirements": [ # Requirements for additional authentication providers.

6238

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6239

# [JSON Web Token

6240

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6241

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6246

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

6247

# implemented and accepted in all the runtime components.

6248

#

6249

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6250

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

6251

# that are allowed to access. A JWT containing any of these audiences will

6252

# be accepted. When this setting is absent, only JWTs with audience

6253

# "https://Service_name/API_name"

6254

# will be accepted. For example, if no audiences are in the setting,

6255

# LibraryService API will only accept JWTs with the following audience

6256

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

6261

# bookstore_web.apps.googleusercontent.com

6262

},

6263

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6264

"allowWithoutCredential": True or False, # If true, the service accepts API keys without any other credential.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6265

"selector": "A String", # Selects the methods to which this rule applies.

6266

#

6267

# Refer to selector for syntax details.

6268

},

6269

],

6270

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6271

{ # Configuration for an authentication provider, including support for

6272

# [JSON Web Token

6273

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6274

"jwtLocations": [ # Defines the locations to extract the JWT.

6275

#

6276

# JWT locations can be either from HTTP headers or URL query parameters.

6277

# The rule is that the first match wins. The checking order is: checking

6278

# all headers first, then URL query parameters.

6279

#

6280

# If not specified, default to use following 3 locations:

6281

# 1) Authorization: Bearer

6282

# 2) x-goog-iap-jwt-assertion

6283

# 3) access_token query parameter

6284

#

6285

# Default locations can be specified as followings:

6286

# jwt_locations:

6287

# - header: Authorization

6288

# value_prefix: "Bearer "

6289

# - header: x-goog-iap-jwt-assertion

6290

# - query: access_token

6291

{ # Specifies a location to extract JWT from an API request.

6292

"query": "A String", # Specifies URL query parameter name to extract JWT token.

6293

"valuePrefix": "A String", # The value prefix. The value format is "value_prefix{token}"

6294

# Only applies to "in" header type. Must be empty for "in" query type.

6295

# If not empty, the header value has to match (case sensitive) this prefix.

6296

# If not matched, JWT will not be extracted. If matched, JWT will be

6297

# extracted after the prefix is removed.

6298

#

6299

# For example, for "Authorization: Bearer {JWT}",

6300

# value_prefix="Bearer " with a space at the end.

6301

"header": "A String", # Specifies HTTP header name to extract JWT token.

6302

},

6303

],

6304

"audiences": "A String", # The list of JWT

6305

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

6306

# that are allowed to access. A JWT containing any of these audiences will

6307

# be accepted. When this setting is absent, JWTs with audiences:

6308

# - "https://[service.name]/[google.protobuf.Api.name]"

6309

# - "https://[service.name]/"

6310

# will be accepted.

6311

# For example, if no audiences are in the setting, LibraryService API will

6312

# accept JWTs with the following audiences:

6313

# -

6314

# https://library-example.googleapis.com/google.example.library.v1.LibraryService

6315

# - https://library-example.googleapis.com/

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

6320

# bookstore_web.apps.googleusercontent.com

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6321

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

6322

# [OpenID

6323

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

6324

# Optional if the key set document:

6325

# - can be retrieved from

6326

# [OpenID

6327

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

6328

# the issuer.

6329

# - can be inferred from the email domain of the issuer (e.g. a Google

6330

# service account).

6331

#

6332

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6333

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

6334

# `AuthRequirement.provider_id`.

6335

#

6336

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6337

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

6338

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6339

"issuer": "A String", # Identifies the principal that issued the JWT. See

6340

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

6341

# Usually a URL or an email address.

6342

#

6343

# Example: https://securetoken.google.com

6344

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

6349

"rules": [ # A list of usage rules that apply to individual API methods.

6350

#

6351

# **NOTE:** All service configuration rules follow "last one wins" order.

6352

{ # Usage configuration rules for the service.

6353

#

6354

# NOTE: Under development.

6355

#

6356

#

6357

# Use this rule to configure unregistered calls for the service. Unregistered

6358

# calls are calls that do not contain consumer project identity.

6359

# (Example: calls that do not contain an API key).

6360

# By default, API methods do not allow unregistered calls, and each method call

6361

# must be identified by a consumer project identity. Use this rule to

6362

# allow/disallow unregistered calls.

6363

#

6364

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

6370

#

6371

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

6376

# allow_unregistered_calls: true

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6377

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

6378

# methods in all APIs.

6379

#

6380

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6381

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

6382

# plane features, such as quota and billing, will not be available.

6383

# This flag is used by Google Cloud Endpoints to bypass checks for internal

6384

# methods, such as service health check methods.

6385

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

6386

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6387

},

6388

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6389

"serviceIdentity": { # The per-product per-project service identity for a service. # The configuration of a per-product per-project service identity.

6390

#

6391

#

6392

# Use this field to configure per-product per-project service identity.

6393

# Example of a service identity configuration.

#

# usage:

# service_identity:

# - service_account_parent: "projects/123456789"

6398

# display_name: "Cloud XXX Service Agent"

6399

# description: "Used as the identity of Cloud XXX to access resources"

6400

"displayName": "A String", # Optional. A user-specified name for the service account.

6401

# Must be less than or equal to 100 UTF-8 bytes.

6402

"description": "A String", # Optional. A user-specified opaque description of the service account.

6403

# Must be less than or equal to 256 UTF-8 bytes.

6404

"serviceAccountParent": "A String", # A service account project that hosts the service accounts.

6405

#

6406

# An example name would be:

6407

# `projects/123456789`

6408

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6409

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

6410

# service producer.

6411

#

6412

# Google Service Management currently only supports

6413

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

6414

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

6415

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

6416

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6417

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6418

# service. Each requirement is of the form <service.name>/<requirement-id>;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6419

# for example 'serviceusage.googleapis.com/billing-enabled'.

6420

"A String",

6421

],

6422

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6423

"configVersion": 42, # The semantic version of the service configuration. The config version

6424

# affects the interpretation of the service configuration. For example,

6425

# certain features are enabled by default for certain config versions.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6426

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6427

# The latest config version is `3`.

6428

"producerProjectId": "A String", # The Google project that owns this service.

6429

"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]

6430

# HttpRule, each specifying the mapping of an RPC method

6431

# to one or more HTTP REST API methods.

6432

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

6433

#

6434

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6435

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6436

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6437

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

6438

# more HTTP REST endpoints. It allows developers to build a single API service

6439

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

6440

# APIs](https://github.com/googleapis/googleapis),

6441

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

6442

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

6443

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

6444

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6445

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6446

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

6447

# how different portions of the gRPC request message are mapped to the URL

6448

# path, URL query parameters, and HTTP request body. It also controls how the

6449

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

6450

# typically specified as an `google.api.http` annotation on the gRPC method.

6451

#

6452

# Each mapping specifies a URL path template and an HTTP method. The path

6453

# template may refer to one or more fields in the gRPC request message, as long

6454

# as each field is a non-repeated field with a primitive (non-message) type.

6455

# The path template controls how fields of the request message are mapped to

6456

# the URL path.

6457

#

6458

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6459

#

6460

# service Messaging {

6461

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6462

# option (google.api.http) = {

6463

# get: "/v1/{name=messages/*}"

6464

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6465

# }

6466

# }

6467

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6468

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6469

# }

6470

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6471

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6472

# }

6473

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6474

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6475

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6476

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6477

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6478

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6479

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6480

# Any fields in the request message which are not bound by the path template

6481

# automatically become HTTP query parameters if there is no HTTP request body.

6482

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6483

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6484

# service Messaging {

6485

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6486

# option (google.api.http) = {

6487

# get:"/v1/messages/{message_id}"

6488

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6489

# }

6490

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6491

# message GetMessageRequest {

6492

# message SubMessage {

6493

# string subfield = 1;

6494

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6495

# string message_id = 1; // Mapped to URL path.

6496

# int64 revision = 2; // Mapped to URL query parameter `revision`.

6497

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6498

# }

6499

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6500

# This enables a HTTP JSON to RPC mapping as below:

6501

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6502

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6503

# -----|-----

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6504

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6505

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

6506

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6507

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6508

# Note that fields which are mapped to URL query parameters must have a

6509

# primitive type or a repeated primitive type or a non-repeated message type.

6510

# 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^]

6511

# 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]

6512

# message is mapped to a separate parameter, such as

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6513

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6514

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6515

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6516

# specifies the mapping. Consider a REST update method on the

6517

# message resource collection:

6518

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6519

# service Messaging {

6520

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

6521

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6522

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

6528

# string message_id = 1; // mapped to the URL

6529

# Message message = 2; // mapped to the body

6530

# }

6531

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6532

# The following HTTP JSON to RPC mapping is enabled, where the

6533

# representation of the JSON in the request body is determined by

6534

# protos JSON encoding:

6535

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6536

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6537

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6538

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6539

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6540

#

6541

# The special name `*` can be used in the body mapping to define that

6542

# every field not bound by the path template should be mapped to the

6543

# request body. This enables the following alternative definition of

6544

# the update method:

6545

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6546

# service Messaging {

6547

# rpc UpdateMessage(Message) returns (Message) {

6548

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6549

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

6556

# string text = 2;

6557

# }

6558

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6559

#

6560

# The following HTTP JSON to RPC mapping is enabled:

6561

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6562

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6563

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6564

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

6565

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6566

#

6567

# Note that when using `*` in the body mapping, it is not possible to

6568

# 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]

6569

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6570

# defining REST APIs. The common usage of `*` is in custom methods

6571

# which don't use the URL at all for transferring data.

6572

#

6573

# It is possible to define multiple HTTP methods for one RPC by using

6574

# the `additional_bindings` option. Example:

6575

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6576

# service Messaging {

6577

# rpc GetMessage(GetMessageRequest) returns (Message) {

6578

# option (google.api.http) = {

6579

# get: "/v1/messages/{message_id}"

6580

# additional_bindings {

6581

# get: "/v1/users/{user_id}/messages/{message_id}"

6582

# }

6583

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6584

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6585

# }

6586

# message GetMessageRequest {

6587

# string message_id = 1;

6588

# string user_id = 2;

6589

# }

6590

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6591

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6592

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6593

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6594

# -----|-----

6595

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6596

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

6597

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6598

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6599

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6600

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6601

# 1. Leaf request fields (recursive expansion nested messages in the request

6602

# message) are classified into three categories:

6603

# - Fields referred by the path template. They are passed via the URL path.

6604

# - Fields referred by the HttpRule.body. They are passed via the HTTP

6605

# request body.

6606

# - All other fields are passed via the URL query parameters, and the

6607

# parameter name is the field path in the request message. A repeated

6608

# field can be represented as multiple query parameters under the same

6609

# name.

6610

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

6611

# are passed via URL path and HTTP request body.

6612

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

6613

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6614

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6615

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6616

#

6617

# Template = "/" Segments [ Verb ] ;

6618

# Segments = Segment { "/" Segment } ;

6619

# Segment = "*" | "**" | LITERAL | Variable ;

6620

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

6621

# FieldPath = IDENT { "." IDENT } ;

6622

# Verb = ":" LITERAL ;

6623

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6624

# The syntax `*` matches a single URL path segment. The syntax `**` matches

6625

# zero or more URL path segments, which must be the last part of the URL path

6626

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6627

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6628

# The syntax `Variable` matches part of the URL path as specified by its

6629

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6630

# matches a single path segment, its template may be omitted, e.g. `{var}`

6631

# is equivalent to `{var=*}`.

6632

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6633

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

6634

# contains any reserved character, such characters should be percent-encoded

6635

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6636

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6637

# If a variable contains exactly one path segment, such as `"{var}"` or

6638

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

6639

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

6640

# server side does the reverse decoding. Such variables show up in the

6641

# [Discovery

6642

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6643

# `{var}`.

6644

#

6645

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

6646

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

6647

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

6648

# The server side does the reverse decoding, except "%2F" and "%2f" are left

6649

# unchanged. Such variables show up in the

6650

# [Discovery

6651

# Document](https://developers.google.com/discovery/v1/reference/apis) as

6652

# `{+var}`.

6653

#

6654

# ## Using gRPC API Service Configuration

6655

#

6656

# gRPC API Service Configuration (service config) is a configuration language

6657

# for configuring a gRPC service to become a user-facing product. The

6658

# service config is simply the YAML representation of the `google.api.Service`

6659

# proto message.

6660

#

6661

# As an alternative to annotating your proto file, you can configure gRPC

6662

# transcoding in your service config YAML files. You do this by specifying a

6663

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

6664

# effect as the proto annotation. This can be particularly useful if you

6665

# have a proto that is reused in multiple services. Note that any transcoding

6666

# specified in the service config will override any matching transcoding

6667

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

6674

# - selector: example.v1.Messaging.GetMessage

6675

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

6680

# proto to JSON conversion must follow the [proto3

6681

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

6682

#

6683

# While the single segment variable follows the semantics of

6684

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

6685

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

6686

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

6687

# does not expand special characters like `?` and `#`, which would lead

6688

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

6689

# for multi segment variables.

6690

#

6691

# The path variables **must not** refer to any repeated or mapped field,

6692

# because client libraries are not capable of handling such variable expansion.

6693

#

6694

# The path variables **must not** capture the leading "/" character. The reason

6695

# is that the most common use case "{var}" does not capture the leading "/"

6696

# character. For consistency, all path variables must share the same behavior.

6697

#

6698

# Repeated message fields must not be mapped to URL query parameters, because

6699

# no client library can support such complicated mapping.

6700

#

6701

# If an API needs to use a JSON array for request or response body, it can map

6702

# the request or response body to a repeated field. However, some gRPC

6703

# Transcoding implementations may not support this feature.

6704

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

6705

# body, or `*` for mapping all request fields not captured by the path

6706

# pattern to the HTTP body, or omitted for not having any HTTP request body.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6707

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6708

# NOTE: the referred field must be present at the top-level of the request

6709

# message type.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6710

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

6711

# resources.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6712

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

6713

# not contain an `additional_bindings` field themselves (that is,

6714

# the nesting may only be one level deep).

6715

# Object with schema name: HttpRule

6716

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6717

"selector": "A String", # Selects a method to which this rule applies.

6718

#

6719

# Refer to selector for syntax details.

6720

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

6721

# response body. When omitted, the entire response message will be used

6722

# as the HTTP response body.

6723

#

6724

# NOTE: The referred field must be present at the top-level of the response

6725

# message type.

6726

"allowHalfDuplex": True or False, # When this flag is set to true, HTTP requests will be allowed to invoke a

6727

# half-duplex streaming method.

6728

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6729

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6730

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6731

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

6732

# included in the `pattern` field, such as HEAD, or "*" to leave the

6733

# HTTP method unspecified for this rule. The wild-card rule is useful

6734

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6735

"path": "A String", # The path matched by this custom verb.

6736

"kind": "A String", # The name of this custom HTTP verb.

6737

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6738

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6739

},

6740

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6741

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parameters will be fully URI-decoded except in

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6742

# cases of single segment matches in reserved expansion, where "%2F" will be

6743

# left encoded.

6744

#

6745

# The default behavior is to not decode RFC 6570 reserved characters in multi

6746

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6747

},

6748

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

6749

# of the google.protobuf.Api needs to be provided by the configuration

6750

# author, as the remaining fields will be derived from the IDL during the

6751

# normalization process. It is an error to specify an API interface here

6752

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6753

{ # Api is a light-weight descriptor for an API Interface.

6754

#

6755

# Interfaces are also described as "protocol buffer services" in some contexts,

6756

# such as by the "service" keyword in a .proto file, but they are different

6757

# from API Services, which represent a concrete implementation of an interface

6758

# as opposed to simply a description of methods and bindings. They are also

6759

# sometimes simply referred to as "APIs" in other contexts, such as the name of

6760

# this message itself. See https://cloud.google.com/apis/design/glossary for

6761

# detailed terminology.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6762

"name": "A String", # The fully qualified name of this interface, including package name

6763

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6764

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

6765

# message.

6766

# protobuf element, like the file in which it is defined.

6767

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6768

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6769

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6770

"mixins": [ # Included interfaces. See Mixin.

6771

{ # Declares an API Interface to be included in this interface. The including

6772

# interface must redeclare all the methods from the included interface, but

6773

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6774

#

6775

# - If after comment and whitespace stripping, the documentation

6776

# string of the redeclared method is empty, it will be inherited

6777

# from the original method.

6778

#

6779

# - Each annotation belonging to the service config (http,

6780

# visibility) which is not set in the redeclared method will be

6781

# inherited.

6782

#

6783

# - If an http annotation is inherited, the path pattern will be

6784

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6785

# version of the including interface plus the root path if

6786

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6787

#

6788

# Example of a simple mixin:

6789

#

6790

# package google.acl.v1;

6791

# service AccessControl {

6792

# // Get the underlying ACL object.

6793

# rpc GetAcl(GetAclRequest) returns (Acl) {

6794

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

6799

# service Storage {

6800

# // rpc GetAcl(GetAclRequest) returns (Acl);

6801

#

6802

# // Get a data record.

6803

# rpc GetData(GetDataRequest) returns (Data) {

6804

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

6809

#

6810

# apis:

6811

# - name: google.storage.v2.Storage

6812

# mixins:

6813

# - name: google.acl.v1.AccessControl

6814

#

6815

# The mixin construct implies that all methods in `AccessControl` are

6816

# also declared with same name and request/response types in

6817

# `Storage`. A documentation generator or annotation processor will

6818

# see the effective `Storage.GetAcl` method after inherting

6819

# documentation and annotations as follows:

6820

#

6821

# service Storage {

6822

# // Get the underlying ACL object.

6823

# rpc GetAcl(GetAclRequest) returns (Acl) {

6824

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

6830

#

6831

# If the `root` field in the mixin is specified, it should be a

6832

# relative path under which inherited HTTP paths are placed. Example:

6833

#

6834

# apis:

6835

# - name: google.storage.v2.Storage

6836

# mixins:

6837

# - name: google.acl.v1.AccessControl

6838

# root: acls

6839

#

6840

# This implies the following inherited HTTP annotation:

6841

#

6842

# service Storage {

6843

# // Get the underlying ACL object.

6844

# rpc GetAcl(GetAclRequest) returns (Acl) {

6845

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

6850

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6851

"name": "A String", # The fully qualified name of the interface which is included.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6852

},

6853

],

6854

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6855

"version": "A String", # A version string for this interface. If specified, must have the form

6856

# `major-version.minor-version`, as in `1.10`. If the minor version is

6857

# omitted, it defaults to zero. If the entire version field is empty, the

6858

# major version is derived from the package name, as outlined below. If the

6859

# field is not empty, the version in the package name will be verified to be

6860

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6861

#

6862

# The versioning schema uses [semantic

6863

# versioning](http://semver.org) where the major version number

6864

# indicates a breaking change and the minor version an additive,

6865

# non-breaking change. Both version numbers are signals to users

6866

# what to expect from different versions, and should be carefully

6867

# chosen based on the product plan.

6868

#

6869

# The major version is also reflected in the package name of the

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6870

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6871

# `google.feature.v1`. For major versions 0 and 1, the suffix can

6872

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6873

# experimental, non-GA interfaces.

6874

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6875

{ # A protocol buffer option, which can be attached to a message, field,

6876

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6877

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6878

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6879

# For custom options, it should be the fully-qualified name. For example,

6880

# `"google.api.http"`.

6881

"value": { # The option's value packed in an Any message. If the value is a primitive,

6882

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6883

# should be used. If the value is an enum, it should be stored as an int32

6884

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6885

"a_key": "", # Properties of the object. Contains field @type with type URL.

6886

},

6887

},

6888

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

6889

"methods": [ # The methods of this interface, in unspecified order.

6890

{ # Method represents a method of an API interface.

6891

"name": "A String", # The simple name of this method.

6892

"requestStreaming": True or False, # If true, the request is streamed.

6893

"responseTypeUrl": "A String", # The URL of the output message type.

6894

"requestTypeUrl": "A String", # A URL of the input message type.

6895

"responseStreaming": True or False, # If true, the response is streamed.

6896

"syntax": "A String", # The source syntax of this method.

6897

"options": [ # Any metadata attached to the method.

6898

{ # A protocol buffer option, which can be attached to a message, field,

6899

# enumeration, etc.

6900

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6901

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6902

# For custom options, it should be the fully-qualified name. For example,

6903

# `"google.api.http"`.

6904

"value": { # The option's value packed in an Any message. If the value is a primitive,

6905

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6906

# should be used. If the value is an enum, it should be stored as an int32

6907

# value using the google.protobuf.Int32Value type.

6908

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6914

},

6915

],

6916

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

6917

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

6925

# - google.foo.v1.AnotherError

6926

"rules": [ # The list of custom error rules that apply to individual API messages.

6927

#

6928

# **NOTE:** All service configuration rules follow "last one wins" order.

6929

{ # A custom error rule.

6930

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

6931

# objects of this type will be filtered when they appear in error payload.

6932

"selector": "A String", # Selects messages to which this rule applies.

6933

#

6934

# Refer to selector for syntax details.

6935

},

6936

],

6937

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

6938

"A String",

6939

],

6940

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6941

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

6942

# usage.

6943

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6944

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6945

# - The service configuration defines a set of metrics.

6946

# - For API calls, the quota.metric_rules maps methods to metrics with

6947

# corresponding costs.

6948

# - The quota.limits defines limits on the metrics, which will be used for

6949

# quota checks at runtime.

6950

#

6951

# An example quota configuration in yaml format:

6952

#

6953

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6954

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6955

#

6956

# - name: apiWriteQpsPerProject

6957

# metric: library.googleapis.com/write_calls

6958

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

6964

# # except for the UpdateBook and DeleteBook methods. These two methods

6965

# # are mapped to the write_calls metric, with the UpdateBook method

6966

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

6971

# - selector: google.example.library.v1.LibraryService.UpdateBook

6972

# metric_costs:

6973

# library.googleapis.com/write_calls: 2

6974

# - selector: google.example.library.v1.LibraryService.DeleteBook

6975

# metric_costs:

6976

# library.googleapis.com/write_calls: 1

6977

#

6978

# Corresponding Metric definition:

6979

#

6980

# metrics:

6981

# - name: library.googleapis.com/read_calls

6982

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

6987

# display_name: Write requests

6988

# metric_kind: DELTA

6989

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6990

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6991

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

6992

# or more metrics.

6993

{ # Bind API methods to metrics. Binding a method to a metric causes that

6994

# metric's configured quota behaviors to apply to the method call.

6995

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

6996

# cost applied to each metric.

6997

#

6998

# The key of the map is the metric name, and the values are the amount

6999

# increased for the metric against which the quota limits are defined.

7000

# The value must not be negative.

7001

"a_key": "A String",

7002

},

7003

"selector": "A String", # Selects the methods to which this rule applies.

7004

#

7005

# Refer to selector for syntax details.

7006

},

7007

],

7008

"limits": [ # List of `QuotaLimit` definitions for the service.

7009

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

7010

# for a limit type. There can be at most one limit for a duration and limit

7011

# type combination defined within a `QuotaGroup`.

7012

"displayName": "A String", # User-visible display name for this limit.

7013

# Optional. If not set, the UI will provide a default display name based on

7014

# the quota configuration. This field can be used to override the default

7015

# display name generated from the configuration.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7016

"description": "A String", # Optional. User-visible, extended description for this quota limit.

7017

# Should be used only when more context is needed to understand this limit

7018

# than provided by the limit's display name (see: `display_name`).

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7019

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

7020

# duration. This is the number of tokens assigned when a client

7021

# application developer activates the service for his/her project.

7022

#

7023

# Specifying a value of 0 will block all requests. This can be used if you

7024

# are provisioning quota to selected consumers and blocking others.

7025

# Similarly, a value of -1 will indicate an unlimited quota. No other

7026

# negative values are allowed.

7027

#

7028

# Used by group-based quotas only.

7029

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

7030

# the same metric will be checked together during runtime. The metric must be

7031

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7032

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

7033

# integer value that is the maximum number of requests allowed for the

7034

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7035

"a_key": "A String",

7036

},

7037

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

7038

# duration. Client application developers can override the default limit up

7039

# to this maximum. If specified, this value cannot be set to a value less

7040

# than the default limit. If not specified, it is set to the default limit.

7041

#

7042

# To allow clients to apply overrides with no upper bound, set this to -1,

7043

# indicating unlimited maximum quota.

7044

#

7045

# Used by group-based quotas only.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7046

"duration": "A String", # Duration of this limit in textual notation. Must be "100s" or "1d".

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7047

#

7048

# Used by group-based quotas only.

7049

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

7050

# The free tier is the number of tokens that will be subtracted from the

7051

# billed amount when billing is enabled.

7052

# This field can only be set on a limit with duration "1d", in a billable

7053

# group; it is invalid on any other limit. If this field is not set, it

7054

# defaults to 0, indicating that there is no free tier for this service.

7055

#

7056

# Used by group-based quotas only.

7057

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

7058

# Metric.unit. The supported unit kinds are determined by the quota

7059

# backend system.

7060

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7061

# Here are some examples:

7062

# * "1/min/{project}" for quota per minute per project.

7063

#

7064

# Note: the order of unit components is insignificant.

7065

# The "1" at the beginning is required to follow the metric unit syntax.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7066

"name": "A String", # Name of the quota limit.

7067

#

7068

# The name must be provided, and it must be unique within the service. The

7069

# name can only include alphanumeric characters as well as '-'.

7070

#

7071

# The maximum length of the limit name is 64 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7076

{ # Defines a metric type and its schema. Once a metric descriptor is created,

7077

# deleting or altering it stops data collection and makes the metric type's

7078

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7079

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

7080

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7081

# This field is optional but it is recommended to be set for any metrics

7082

# associated with user-visible concepts, such as Quota.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7083

"description": "A String", # A detailed description of the metric, which can be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7084

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7085

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7086

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7087

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7088

"labels": [ # The set of labels that can be used to describe a specific

7089

# instance of this metric type. For example, the

7090

# `appengine.googleapis.com/http/server/response_latencies` metric

7091

# type has a label for the HTTP response code, `response_code`, so

7092

# you can look at latencies for successful responses or just

7093

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7094

{ # A description of a label.

7095

"valueType": "A String", # The type of data that can be assigned to the label.

7096

"description": "A String", # A human-readable description for the label.

7097

"key": "A String", # The label key.

7098

},

7099

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7100

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7101

"monitoredResourceTypes": [ # Read-only. If present, then a time

7102

# series, which is identified partially by

7103

# a metric type and a MonitoredResourceDescriptor, that is associated

7104

# with this metric type can only be associated with one of the monitored

7105

# resource types listed here.

7106

"A String",

7107

],

7108

"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.

7109

"launchStage": "A String", # Deprecated. Must use the MetricDescriptor.launch_stage instead.

7110

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

7111

# age are guaranteed to be ingested and available to be read, excluding

7112

# data loss due to errors.

7113

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

7114

# periodically, consecutive data points are stored at this time interval,

7115

# excluding data loss due to errors. Metrics with a higher granularity have

7116

# a smaller sampling period.

7117

},

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7118

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7119

# URL-encoded. All user-defined metric types have the DNS name

7120

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

7121

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7122

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7123

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7124

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7125

# "appengine.googleapis.com/http/server/response_latencies"

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7126

"unit": "A String", # The units in which the metric value is reported. It is only applicable

7127

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The `unit`

7128

# defines the representation of the stored metric values.

7129

#

7130

# Different systems may scale the values to be more easily displayed (so a

7131

# value of `0.02KBy` _might_ be displayed as `20By`, and a value of

7132

# `3523KBy` _might_ be displayed as `3.5MBy`). However, if the `unit` is

7133

# `KBy`, then the value of the metric is always in thousands of bytes, no

7134

# matter how it may be displayed..

7135

#

7136

# If you want a custom metric to record the exact number of CPU-seconds used

7137

# by a job, you can create an `INT64 CUMULATIVE` metric whose `unit` is

7138

# `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005

7139

# CPU-seconds, then the value is written as `12005`.

7140

#

7141

# Alternatively, if you want a custom metric to record data in a more

7142

# granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is

7143

# `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),

7144

# or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).

7145

#

7146

# The supported units are a subset of [The Unified Code for Units of

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7147

# Measure](http://unitsofmeasure.org/ucum.html) standard:

7148

#

7149

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

7159

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

# * `k` kilo (10^3)

# * `M` mega (10^6)

# * `G` giga (10^9)

# * `T` tera (10^12)

# * `P` peta (10^15)

# * `E` exa (10^18)

# * `Z` zetta (10^21)

7167

# * `Y` yotta (10^24)

7168

#

7169

# * `m` milli (10^-3)

7170

# * `u` micro (10^-6)

7171

# * `n` nano (10^-9)

7172

# * `p` pico (10^-12)

7173

# * `f` femto (10^-15)

7174

# * `a` atto (10^-18)

7175

# * `z` zepto (10^-21)

7176

# * `y` yocto (10^-24)

#

# * `Ki` kibi (2^10)

# * `Mi` mebi (2^20)

# * `Gi` gibi (2^30)

# * `Ti` tebi (2^40)

# * `Pi` pebi (2^50)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7183

#

7184

# **Grammar**

7185

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7186

# The grammar also includes these connectors:

7187

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7188

# * `/` division or ratio (as an infix operator). For examples,

7189

# `kBy/{email}` or `MiBy/10ms` (although you should almost never

7190

# have `/s` in a metric `unit`; rates should always be computed at

7191

# query time from the underlying cumulative or delta value).

7192

# * `.` multiplication or composition (as an infix operator). For

7193

# examples, `GBy.d` or `k{watt}.h`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7194

#

7195

# The grammar for a unit is as follows:

7196

#

7197

# Expression = Component { "." Component } { "/" Component } ;

7198

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7199

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

7205

#

7206

# Notes:

7207

#

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7208

# * `Annotation` is just a comment if it follows a `UNIT`. If the annotation

7209

# is used alone, then the unit is equivalent to `1`. For examples,

7210

# `{request}/s == 1/s`, `By{transmitted}/s == By/s`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7211

# * `NAME` is a sequence of non-blank printable ASCII characters not

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7212

# containing `{` or `}`.

7213

# * `1` represents a unitary [dimensionless

7214

# unit](https://en.wikipedia.org/wiki/Dimensionless_quantity) of 1, such

7215

# as in `1/s`. It is typically used when none of the basic units are

7216

# appropriate. For example, "new users per day" can be represented as

7217

# `1/d` or `{new-users}/d` (and a metric value `5` would mean "5 new

7218

# users). Alternatively, "thousands of page views per day" would be

7219

# represented as `1000/d` or `k1/d` or `k{page_views}/d` (and a metric

7220

# value of `5.3` would mean "5300 page views per day").

7221

# * `%` represents dimensionless value of 1/100, and annotates values giving

7222

# a percentage (so the metric values are typically in the range of 0..100,

7223

# and a metric value `3` means "3 percent").

7224

# * `10^2.%` indicates a metric contains a ratio, typically in the range

7225

# 0..1, that will be multiplied by 100 and displayed as a percentage

7226

# (so a metric value `0.03` means "3 percent").

7227

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7228

},

7229

],

7230

"enums": [ # A list of all enum types included in this API service. Enums

7231

# referenced directly or indirectly by the `apis` are automatically

7232

# included. Enums which are not referenced but shall be included

7233

# should be listed here by name. Example:

7234

#

7235

# enums:

7236

# - name: google.someapi.v1.SomeEnum

7237

{ # Enum type definition.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7238

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7239

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

7240

# protobuf element, like the file in which it is defined.

7241

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7242

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

7243

},

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7244

"options": [ # Protocol buffer options.

7245

{ # A protocol buffer option, which can be attached to a message, field,

7246

# enumeration, etc.

7247

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7248

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7249

# For custom options, it should be the fully-qualified name. For example,

7250

# `"google.api.http"`.

7251

"value": { # The option's value packed in an Any message. If the value is a primitive,

7252

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7253

# should be used. If the value is an enum, it should be stored as an int32

7254

# value using the google.protobuf.Int32Value type.

7255

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7260

"enumvalue": [ # Enum value definitions.

7261

{ # Enum value definition.

7262

"options": [ # Protocol buffer options.

7263

{ # A protocol buffer option, which can be attached to a message, field,

7264

# enumeration, etc.

7265

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7266

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7267

# For custom options, it should be the fully-qualified name. For example,

7268

# `"google.api.http"`.

7269

"value": { # The option's value packed in an Any message. If the value is a primitive,

7270

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7271

# should be used. If the value is an enum, it should be stored as an int32

7272

# value using the google.protobuf.Int32Value type.

7273

"a_key": "", # Properties of the object. Contains field @type with type URL.

7274

},

7275

},

7276

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7277

"number": 42, # Enum value number.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7278

"name": "A String", # Enum value name.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7279

},

7280

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7281

},

7282

],

7283

"types": [ # A list of all proto message types included in this API service.

7284

# Types referenced directly or indirectly by the `apis` are

7285

# automatically included. Messages which are not referenced but

7286

# shall be included, such as types used by the `google.protobuf.Any` type,

7287

# should be listed here by name. Example:

7288

#

7289

# types:

7290

# - name: google.protobuf.Int32

7291

{ # A protocol buffer message type.

7292

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

7293

"A String",

7294

],

7295

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7296

"fields": [ # The list of fields.

7297

{ # A single field of a message type.

7298

"kind": "A String", # The field type.

7299

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

7300

# types. The first type has index 1; zero means the type is not in the list.

7301

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

7302

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

7303

"name": "A String", # The field name.

7304

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

7305

"jsonName": "A String", # The field JSON name.

7306

"number": 42, # The field number.

7307

"cardinality": "A String", # The field cardinality.

7308

"options": [ # The protocol buffer options.

7309

{ # A protocol buffer option, which can be attached to a message, field,

7310

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7311

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7312

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7313

# For custom options, it should be the fully-qualified name. For example,

7314

# `"google.api.http"`.

7315

"value": { # The option's value packed in an Any message. If the value is a primitive,

7316

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7317

# should be used. If the value is an enum, it should be stored as an int32

7318

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7319

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

7324

},

7325

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7326

"syntax": "A String", # The source syntax.

7327

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

7328

# protobuf element, like the file in which it is defined.

7329

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7330

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

7331

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7332

"options": [ # The protocol buffer options.

7333

{ # A protocol buffer option, which can be attached to a message, field,

7334

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7335

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7336

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7337

# For custom options, it should be the fully-qualified name. For example,

7338

# `"google.api.http"`.

7339

"value": { # The option's value packed in an Any message. If the value is a primitive,

7340

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7341

# should be used. If the value is an enum, it should be stored as an int32

7342

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7343

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7349

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7350

#

7351

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7352

# producer and consumer projects. In the example, the `activity_history`

7353

# log is sent to both the producer and consumer projects, whereas the

7354

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7355

#

7356

# monitored_resources:

7357

# - type: library.googleapis.com/branch

7358

# labels:

7359

# - key: /city

7360

# description: The city where the library branch is located in.

7361

# - key: /name

7362

# description: The name of the branch.

7363

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7364

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7365

# labels:

7366

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7367

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7368

# logging:

7369

# producer_destinations:

7370

# - monitored_resource: library.googleapis.com/branch

7371

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7372

# - activity_history

7373

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7374

# consumer_destinations:

7375

# - monitored_resource: library.googleapis.com/branch

7376

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7377

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7378

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

7379

# There can be multiple producer destinations, each one must have a

7380

# different monitored resource type. A log can be used in at most

7381

# one producer destination.

7382

{ # Configuration of a specific logging destination (the producer project

7383

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7384

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7385

# Service.monitored_resources section.

7386

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7387

# be defined in the Service.logs section. If the log name is

7388

# not a domain scoped name, it will be automatically prefixed with

7389

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

7395

# There can be multiple consumer destinations, each one must have a

7396

# different monitored resource type. A log can be used in at most

7397

# one consumer destination.

7398

{ # Configuration of a specific logging destination (the producer project

7399

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7400

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7401

# Service.monitored_resources section.

7402

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7403

# be defined in the Service.logs section. If the log name is

7404

# not a domain scoped name, it will be automatically prefixed with

7405

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7411

"name": "A String", # The service name, which is a DNS-like logical identifier for the

7412

# service, such as `calendar.googleapis.com`. The service name

7413

# typically goes through DNS verification to make sure the owner

7414

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7415

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

7416

#

7417

# Example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7418

# <pre><code>documentation:

7419

# summary: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7420

# The Google Calendar API gives access

7421

# to most calendar features.

7422

# pages:

7423

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7424

# content: &#40;== include google/foo/overview.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7425

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7426

# content: &#40;== include google/foo/tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7427

# subpages;

7428

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7429

# content: &#40;== include google/foo/tutorial_java.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7430

# rules:

7431

# - selector: google.calendar.Calendar.Get

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7432

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7433

# ...

7434

# - selector: google.calendar.Calendar.Put

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7435

# description: >

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7436

# ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7437

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7438

# Documentation is provided in markdown syntax. In addition to

7439

# standard markdown features, definition lists, tables and fenced

7440

# code blocks are supported. Section headers can be provided and are

7441

# interpreted relative to the section nesting of the context where

7442

# a documentation fragment is embedded.

7443

#

7444

# Documentation from the IDL is merged with documentation defined

7445

# via the config at normalization time, where documentation provided

7446

# by config rules overrides IDL provided.

7447

#

7448

# A number of constructs specific to the API platform are supported

7449

# in documentation text.

7450

#

7451

# In order to reference a proto element, the following

7452

# notation can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7453

# <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7454

# To override the display text used for the link, this can be used:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7455

# <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7456

# Text can be excluded from doc using the following notation:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7457

# <pre><code>&#40;-- internal comment --&#41;</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7458

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7459

# A few directives are available in documentation. Note that

7460

# directives must appear on a single line to be properly

7461

# identified. The `include` directive includes a markdown file from

7462

# an external source:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7463

# <pre><code>&#40;== include path/to/file ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7464

# The `resource_for` directive marks a message to be the resource of

7465

# a collection in REST view. If it is not specified, tools attempt

7466

# to infer the resource from the operations in a collection:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7467

# <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7468

# The directive `suppress_warning` does not directly affect documentation

7469

# and is documented together with service config validation.

7470

"rules": [ # A list of documentation rules that apply to individual API elements.

7471

#

7472

# **NOTE:** All service configuration rules follow "last one wins" order.

7473

{ # A documentation rule provides information about individual API elements.

7474

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7475

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

7476

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7477

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

7478

# qualified name of the element which may end in "*", indicating a wildcard.

7479

# Wildcards are only allowed at the end and for a whole component of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7480

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

7481

# wildcard will match one or more components. To specify a default for all

7482

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7483

},

7484

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7485

"documentationRootUrl": "A String", # The URL to the root of documentation.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7486

"summary": "A String", # A short summary of what the service does. Can only be provided by

7487

# plain text.

7488

"serviceRootUrl": "A String", # Specifies the service root url if the default one (the service name

7489

# from the yaml file) is not suitable. This can be seen in any fully

7490

# specified service urls as well as sections that show a base that other

7491

# urls are relative to.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

7492

"overview": "A String", # Declares a single overview page. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7493

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

7494

# summary: ...

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7495

# overview: &#40;== include overview.md ==&#41;

7496

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

7497

# This is a shortcut for the following declaration (using pages style):

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7498

# <pre><code>documentation:

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

7499

# summary: ...

7500

# pages:

7501

# - name: Overview

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7502

# content: &#40;== include overview.md ==&#41;

7503

# </code></pre>

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

7504

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7505

"pages": [ # The top level pages for the documentation set.

7506

{ # Represents a documentation page. A page can contain subpages to represent

7507

# nested documentation set structure.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7508

"content": "A String", # The Markdown content of the page. You can use <code>&#40;== include {path}

7509

# ==&#41;</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7510

"subpages": [ # Subpages of this page. The order of subpages specified here will be

7511

# honored in the generated docset.

7512

# Object with schema name: Page

7513

],

7514

"name": "A String", # The name of the page. It will be used as an identity of the page to

7515

# generate URI of the page, text of the link to this page in navigation,

7516

# etc. The full page name (start from the root page name to this page

7517

# concatenated with `.`) can be used as reference to the page in your

7518

# documentation. For example:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7519

# <pre><code>pages:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7520

# - name: Tutorial

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7521

# content: &#40;== include tutorial.md ==&#41;

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7522

# subpages:

7523

# - name: Java

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7524

# content: &#40;== include tutorial_java.md ==&#41;

7525

# </code></pre>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7526

# You can reference `Java` page using Markdown reference link syntax:

7527

# `Java`.

7528

},

7529

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7530

},

7531

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

7532

"sourceFiles": [ # All files used during config generation.

7533

{

7534

"a_key": "", # Properties of the object. Contains field @type with type URL.

7535

},

7536

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7537

},

7538

"systemTypes": [ # A list of all proto message types included in this API service.

7539

# It serves similar purpose as [google.api.Service.types], except that

7540

# these types are not needed by user-defined APIs. Therefore, they will not

7541

# show up in the generated discovery doc. This field should only be used

7542

# to define system APIs in ESF.

7543

{ # A protocol buffer message type.

7544

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

7545

"A String",

7546

],

7547

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7548

"fields": [ # The list of fields.

7549

{ # A single field of a message type.

7550

"kind": "A String", # The field type.

7551

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

7552

# types. The first type has index 1; zero means the type is not in the list.

7553

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

7554

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

7555

"name": "A String", # The field name.

7556

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

7557

"jsonName": "A String", # The field JSON name.

7558

"number": 42, # The field number.

7559

"cardinality": "A String", # The field cardinality.

7560

"options": [ # The protocol buffer options.

7561

{ # A protocol buffer option, which can be attached to a message, field,

7562

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7563

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7564

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7565

# For custom options, it should be the fully-qualified name. For example,

7566

# `"google.api.http"`.

7567

"value": { # The option's value packed in an Any message. If the value is a primitive,

7568

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7569

# should be used. If the value is an enum, it should be stored as an int32

7570

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7571

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

7576

},

7577

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7578

"syntax": "A String", # The source syntax.

7579

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

7580

# protobuf element, like the file in which it is defined.

7581

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

7582

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

7583

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7584

"options": [ # The protocol buffer options.

7585

{ # A protocol buffer option, which can be attached to a message, field,

7586

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

7587

"name": "A String", # The option's name. For protobuf built-in options (options defined in

7588

# descriptor.proto), this is the short name. For example, `"map_entry"`.

7589

# For custom options, it should be the fully-qualified name. For example,

7590

# `"google.api.http"`.

7591

"value": { # The option's value packed in an Any message. If the value is a primitive,

7592

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

7593

# should be used. If the value is an enum, it should be stored as an int32

7594

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7595

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"context": { # `Context` defines which contexts an API requests. # Context configuration.

#

# Example:

#

# context:

# rules:

# - selector: "*"

# requested:

# - google.rpc.context.ProjectContext

7610

# - google.rpc.context.OriginContext

7611

#

7612

# The above specifies that all methods in the API request

7613

# `google.rpc.context.ProjectContext` and

7614

# `google.rpc.context.OriginContext`.

7615

#

7616

# Available context types are defined in package

7617

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7618

#

7619

# This also provides mechanism to whitelist any protobuf message extension that

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7620

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

7621

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7622

# 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"

7630

# allowed_request_extensions:

7631

# - google.foo.v1.NewExtension

7632

# allowed_response_extensions:

7633

# - google.foo.v1.NewExtension

7634

#

7635

# You can also specify extension ID instead of fully qualified extension name

7636

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7637

"rules": [ # A list of RPC context rules that apply to individual API methods.

7638

#

7639

# **NOTE:** All service configuration rules follow "last one wins" order.

7640

{ # A context rule provides information about the context for an individual API

7641

# element.

7642

"provided": [ # A list of full type names of provided contexts.

7643

"A String",

7644

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7645

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7646

# side channel from backend to client.

7647

"A String",

7648

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7649

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

7650

# side channel from client to backend.

7651

"A String",

7652

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7653

"requested": [ # A list of full type names of requested contexts.

7654

"A String",

7655

],

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7656

"selector": "A String", # Selects the methods to which this rule applies.

7657

#

7658

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7659

},

7660

],

7661

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7662

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

7663

# with the same name as the service is automatically generated to service all

7664

# defined APIs.

7665

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

7666

# A service may expose any number of endpoints, and all endpoints share the

7667

# same service configuration, such as quota configuration and monitoring

7668

# configuration.

7669

#

7670

# Example service configuration:

7671

#

7672

# name: library-example.googleapis.com

7673

# endpoints:

7674

# # Below entry makes 'google.example.library.v1.Library'

7675

# # API be served from endpoint address library-example.googleapis.com.

7676

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

7677

# # it to decide whether the subsequent cross-origin request is

7678

# # allowed to proceed.

7679

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7680

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7681

"allowCors": True or False, # Allowing

7682

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

7683

# cross-domain traffic, would allow the backends served from this endpoint to

7684

# receive and respond to HTTP OPTIONS requests. The response will be used by

7685

# the browser to determine whether the subsequent cross-origin request is

7686

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7687

"target": "A String", # The specification of an Internet routable address of API frontend that will

7688

# handle requests to this [API

7689

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

7690

# either a valid IPv4 address or a fully-qualified domain name. For example,

7691

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

7692

"features": [ # The list of features enabled on this endpoint.

7693

"A String",

7694

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7695

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7696

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7697

# please specify multiple google.api.Endpoint for each of the intended

7698

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7699

#

7700

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

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>

7712

<pre>Retrieves the next page of results.

7713

7714

Args:

7715

previous_request: The request for the previous page. (required)

7716

previous_response: The response from the request for the previous page. (required)

7717

7718

Returns:

7719

A request object that you can call 'execute()' on to request the next

7720

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^]

7725

<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]

7726

<pre>Creates a new service configuration (version) for a managed service based

7727

on

7728

user-supplied configuration source files (for example: OpenAPI

7729

Specification). This method stores the source configurations as well as the

7730

generated service configuration. To rollout the service configuration to

7731

other services,

7732

please call CreateServiceRollout.

7733

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7734

Only the 100 most recent configuration sources and ones referenced by

7735

existing service configurtions are kept for each service. The rest will be

7736

deleted eventually.

7737

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7738

Operation<response: SubmitConfigSourceResponse>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7739

7740

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7741

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]

7742

for naming requirements. For example: `example.googleapis.com`. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7743

body: object, The request body.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7744

The object takes the form of:

7745

7746

{ # Request message for SubmitConfigSource method.

7747

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7748

# `google.api.Service` configuration based on the `ConfigSource` provided,

7749

# but the generated config and the sources will NOT be persisted.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame^]

7750

"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]

7751

# defined by `google.api.Service`.

7752

"files": [ # Set of source configuration files that are used to generate a service

7753

# configuration (`google.api.Service`).

7754

{ # Generic specification of a source configuration file

7755

"fileContents": "A String", # The bytes that constitute the file.

7756

"fileType": "A String", # The type of configuration file this represents.

7757

"filePath": "A String", # The file name of the configuration file (full or relative path).

7758

},

7759

],

7760

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7761

# by the client for tracking purpose. If empty, the server may choose to

7762

# generate one instead.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

7773

7774

{ # This resource represents a long-running operation that is the result of a

7775

# network API call.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7776

"metadata": { # Service-specific metadata associated with the operation. It typically

7777

# contains progress information and common metadata such as create time.

7778

# Some services might not provide such metadata. Any method that returns a

7779

# long-running operation should document the metadata type, if any.

7780

"a_key": "", # Properties of the object. Contains field @type with type URL.

7781

},

Bu Sun Kim