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

Thomas Coffee

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

[diff] [blame]

78

<code><a href="#create">create(serviceName, body, 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

Thomas Coffee

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

[diff] [blame]

90

<code><a href="#submit">submit(serviceName, body, 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

Thomas Coffee

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

[diff] [blame]

94

<code class="details" id="create">create(serviceName, body, 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:

105

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

106

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

107

body: object, The request body. (required)

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.

Bu Sun Kim

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

[diff] [blame^]

150

#

151

# Next ID: 10

Thomas Coffee

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

[diff] [blame]

152

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

153

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

154

# without any article or other determiners. For example,

155

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

156

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

157

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

158

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

159

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

160

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

161

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

Bu Sun Kim

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

[diff] [blame^]

162

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

163

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

164

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

165

{ # A description of a label.

166

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

167

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

168

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

169

},

170

],

171

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

172

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

173

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

174

# The maximum length of this value is 256 characters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

175

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

176

# be used in documentation.

Jon Wayne Parrott

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

[diff] [blame]

177

},

178

],

179

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

180

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

181

#

182

# - name: library.googleapis.com/activity_history

183

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

184

# display_name: Activity

185

# labels:

186

# - key: /customer_id

187

# description: Identifier of a library customer

188

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

189

# Runtime requests that contain labels not specified here are

190

# considered invalid.

191

{ # A description of a label.

192

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

193

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

194

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

195

},

196

],

197

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

198

# the user interface and should be concise.

Jon Wayne Parrott

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

[diff] [blame]

199

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

200

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

201

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

202

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

Thomas Coffee

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

[diff] [blame]

203

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

204

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

205

},

206

],

Thomas Coffee

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

[diff] [blame]

207

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

208

#

209

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

210

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

211

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

212

# change the names of the system parameters.

213

"rules": [ # Define system parameters.

214

#

215

# The parameters defined here will override the default parameters

216

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

217

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

218

# and names is implementation-dependent.

219

#

220

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

228

#

229

#

230

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

235

# parameters:

236

# - name: api_key

237

# http_header: Api-Key1

238

# - name: api_key

239

# http_header: Api-Key2

240

#

241

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

242

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

243

# methods.

244

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

245

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

246

# names are used the behavior is implementation-dependent.

247

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

248

# parameter-dependent.

249

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

250

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

251

# is implementation-dependent.

252

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

253

# sensitive.

254

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

255

# insensitive.

256

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

257

},

258

],

259

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

260

# methods in all APIs.

261

#

262

# Refer to selector for syntax details.

263

},

264

],

265

},

Sai Cheemalapati

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

[diff] [blame]

266

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

267

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

Bu Sun Kim

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

[diff] [blame^]

268

# generate one instead. Must be no longer than 60 characters.

Jon Wayne Parrott

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

[diff] [blame]

269

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

270

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

271

#

272

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

273

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

Bu Sun Kim

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

[diff] [blame^]

274

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

275

"pathTranslation": "A String",

276

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

277

# value lower than this will be rejected.

Jon Wayne Parrott

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

[diff] [blame]

278

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

279

#

280

# Refer to selector for syntax details.

Bu Sun Kim

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

[diff] [blame^]

281

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

282

# operation. The default is no deadline.

283

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

284

# deadline for gRPC is infinite (no deadline) and HTTP requests is 5 seconds.

Jon Wayne Parrott

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

[diff] [blame]

285

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

286

},

287

],

288

},

Sai Cheemalapati

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

[diff] [blame]

289

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

Jon Wayne Parrott

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

[diff] [blame]

290

#

291

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

292

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

293

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

294

# to both producer and consumer projects, whereas the

295

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

296

# consumer project.

297

#

298

# monitored_resources:

299

# - type: library.googleapis.com/branch

300

# labels:

301

# - key: /city

302

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

303

# - key: /name

304

# description: The name of the branch.

305

# metrics:

306

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

311

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

316

# monitoring:

317

# producer_destinations:

318

# - monitored_resource: library.googleapis.com/branch

319

# metrics:

320

# - library.googleapis.com/book/returned_count

321

# consumer_destinations:

322

# - monitored_resource: library.googleapis.com/branch

323

# metrics:

324

# - library.googleapis.com/book/returned_count

325

# - library.googleapis.com/book/overdue_count

326

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

Bu Sun Kim

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

[diff] [blame^]

327

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

328

# appear in multiple monitoring destinations if different aggregations are

329

# needed for different sets of metrics associated with that monitored

330

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

331

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

332

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

333

# or the consumer project).

334

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

335

# Service.monitored_resources section.

Bu Sun Kim

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

[diff] [blame^]

336

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

337

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

343

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

344

# appear in multiple monitoring destinations if different aggregations are

345

# needed for different sets of metrics associated with that monitored

346

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

347

# in the Monitoring configuration.

Jon Wayne Parrott

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

[diff] [blame]

348

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

349

# or the consumer project).

350

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

351

# Service.monitored_resources section.

Bu Sun Kim

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

[diff] [blame^]

352

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

353

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

"A String",

],

},

],

},

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

360

#

361

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

362

# for billing:

363

#

364

# monitored_resources:

365

# - type: library.googleapis.com/branch

366

# labels:

367

# - key: /city

368

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

369

# - key: /name

370

# description: The name of the branch.

371

# metrics:

372

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

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

377

# - monitored_resource: library.googleapis.com/branch

378

# metrics:

379

# - library.googleapis.com/book/borrowed_count

380

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

381

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

382

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

383

# one consumer destination.

384

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

385

# bill against consumer project).

386

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

387

# Service.monitored_resources section.

388

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

Jon Wayne Parrott

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

[diff] [blame]

389

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

"A String",

],

},

],

},

Bu Sun Kim

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

[diff] [blame^]

395

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

Jon Wayne Parrott

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

[diff] [blame]

396

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

397

#

398

# Example for an API targeted for external use:

399

#

400

# name: calendar.googleapis.com

401

# authentication:

Jon Wayne Parrott

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

[diff] [blame]

402

# providers:

403

# - id: google_calendar_auth

404

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

405

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

Jon Wayne Parrott

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

[diff] [blame]

406

# rules:

407

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame]

408

# requirements:

409

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

410

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

411

#

412

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

413

{ # Authentication rules for the service.

414

#

415

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

416

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

417

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

418

# request.

419

#

420

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

421

# ignored.

422

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

423

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

424

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

425

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

426

#

427

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

428

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

429

#

430

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

431

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

432

# the OAuth scope across all of those APIs.

433

#

434

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

435

# management about how developers will use them in practice.

436

#

437

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

438

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

439

# due to the backend requiring additional scopes or permissions.

440

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

441

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

#

# Example:

#

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

446

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

447

},

Bu Sun Kim

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

[diff] [blame^]

448

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

449

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

450

{ # User-defined authentication requirements, including support for

Bu Sun Kim

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

[diff] [blame^]

451

# [JSON Web Token

452

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

453

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame]

458

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

459

# implemented and accepted in all the runtime components.

460

#

461

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

462

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

463

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

464

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

465

# "https://Service_name/API_name"

466

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

467

# LibraryService API will only accept JWTs with the following audience

468

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

473

# bookstore_web.apps.googleusercontent.com

474

},

475

],

Jon Wayne Parrott

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

[diff] [blame]

476

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

477

#

478

# Refer to selector for syntax details.

479

},

480

],

481

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

Bu Sun Kim

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

[diff] [blame^]

482

{ # Configuration for an authentication provider, including support for

483

# [JSON Web Token

484

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

485

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

486

# [OpenID

487

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

488

# Optional if the key set document:

489

# - can be retrieved from

490

# [OpenID

491

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

492

# the issuer.

493

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

494

# service account).

495

#

496

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

Jon Wayne Parrott

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

[diff] [blame]

497

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

498

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

499

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

500

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

501

# "https://Service_name/API_name"

502

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

503

# LibraryService API will only accept JWTs with the following audience

504

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

509

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

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

[diff] [blame]

510

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

511

# `AuthRequirement.provider_id`.

512

#

513

# Example: "bookstore_auth".

Bu Sun Kim

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

[diff] [blame^]

514

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

515

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

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

[diff] [blame]

516

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

517

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

518

# Usually a URL or an email address.

519

#

520

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

521

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

},

],

},

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

526

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

527

#

528

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

529

{ # Usage configuration rules for the service.

530

#

531

# NOTE: Under development.

532

#

533

#

534

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

535

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

536

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

537

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

538

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

539

# allow/disallow unregistered calls.

540

#

541

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

547

#

548

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

#

# usage:

# rules:

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

553

# allow_unregistered_calls: true

Bu Sun Kim

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

[diff] [blame^]

554

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

555

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

556

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

557

# methods, such as service health check methods.

558

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

559

# that don't identify any user or application.

Jon Wayne Parrott

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

[diff] [blame]

560

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

561

# methods in all APIs.

562

#

563

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

564

},

565

],

Jon Wayne Parrott

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

[diff] [blame]

566

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

567

# service producer.

568

#

569

# Google Service Management currently only supports

570

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

571

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

572

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

573

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

Jon Wayne Parrott

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

[diff] [blame]

574

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

575

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

576

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

577

"A String",

578

],

579

},

Bu Sun Kim

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

[diff] [blame^]

580

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

581

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

582

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

583

# The latest config version is `3`.

584

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

585

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

586

# HttpRule, each specifying the mapping of an RPC method

587

# to one or more HTTP REST API methods.

588

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

589

#

590

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

Bu Sun Kim

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

[diff] [blame^]

591

{ # # gRPC Transcoding

Jon Wayne Parrott

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

[diff] [blame]

592

#

Bu Sun Kim

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

[diff] [blame^]

593

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

594

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

595

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

596

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

597

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

598

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

599

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

600

# and use it for large scale production services.

Jon Wayne Parrott

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

[diff] [blame]

601

#

Bu Sun Kim

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

[diff] [blame^]

602

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

603

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

604

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

605

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

606

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

607

#

608

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

609

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

610

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

611

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

612

# the URL path.

613

#

614

# Example:

Jon Wayne Parrott

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

[diff] [blame]

615

#

616

# service Messaging {

617

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame^]

618

# option (google.api.http) = {

619

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

620

# };

Jon Wayne Parrott

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

[diff] [blame]

621

# }

622

# }

623

# message GetMessageRequest {

Bu Sun Kim

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

[diff] [blame^]

624

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

Jon Wayne Parrott

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

[diff] [blame]

625

# }

626

# message Message {

Bu Sun Kim

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

[diff] [blame^]

627

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

Jon Wayne Parrott

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

[diff] [blame]

628

# }

629

#

Bu Sun Kim

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

[diff] [blame^]

630

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

Jon Wayne Parrott

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

[diff] [blame]

631

#

Bu Sun Kim

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

[diff] [blame^]

632

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

633

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

Bu Sun Kim

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

[diff] [blame^]

634

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

Jon Wayne Parrott

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

[diff] [blame]

635

#

Bu Sun Kim

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

[diff] [blame^]

636

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

637

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

638

# For example:

Jon Wayne Parrott

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

[diff] [blame]

639

#

Sai Cheemalapati

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

[diff] [blame]

640

# service Messaging {

641

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

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

[diff] [blame^]

642

# option (google.api.http) = {

643

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

644

# };

Sai Cheemalapati

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

[diff] [blame]

645

# }

646

# }

Jon Wayne Parrott

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

[diff] [blame]

647

# message GetMessageRequest {

648

# message SubMessage {

649

# string subfield = 1;

650

# }

Bu Sun Kim

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

[diff] [blame^]

651

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

652

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

653

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

Jon Wayne Parrott

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

[diff] [blame]

654

# }

655

#

Jon Wayne Parrott

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

[diff] [blame]

656

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

657

#

Bu Sun Kim

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

[diff] [blame^]

658

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

659

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

Bu Sun Kim

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

[diff] [blame^]

660

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

661

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

662

# "foo"))`

Jon Wayne Parrott

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

[diff] [blame]

663

#

Bu Sun Kim

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

[diff] [blame^]

664

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

665

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

666

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

667

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

668

# message is mapped to a separate parameter, such as

669

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

Jon Wayne Parrott

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

[diff] [blame]

670

#

Bu Sun Kim

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

[diff] [blame^]

671

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

Jon Wayne Parrott

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

[diff] [blame]

672

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

673

# message resource collection:

674

#

Jon Wayne Parrott

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

[diff] [blame]

675

# service Messaging {

676

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

677

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame^]

678

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

Jon Wayne Parrott

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

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

684

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

685

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

686

# }

687

#

Jon Wayne Parrott

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

[diff] [blame]

688

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

689

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

690

# protos JSON encoding:

691

#

Bu Sun Kim

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

[diff] [blame^]

692

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

693

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

Bu Sun Kim

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

[diff] [blame^]

694

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

695

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

Jon Wayne Parrott

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

[diff] [blame]

696

#

697

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

698

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

699

# request body. This enables the following alternative definition of

700

# the update method:

701

#

Jon Wayne Parrott

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

[diff] [blame]

702

# service Messaging {

703

# rpc UpdateMessage(Message) returns (Message) {

704

# option (google.api.http) = {

Bu Sun Kim

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

[diff] [blame^]

705

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

Jon Wayne Parrott

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

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

712

# string text = 2;

713

# }

714

#

Jon Wayne Parrott

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

[diff] [blame]

715

#

716

# The following HTTP JSON to RPC mapping is enabled:

717

#

Bu Sun Kim

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

[diff] [blame^]

718

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

719

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

Bu Sun Kim

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

[diff] [blame^]

720

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

721

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

Jon Wayne Parrott

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

[diff] [blame]

722

#

723

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

724

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

725

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

Jon Wayne Parrott

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

[diff] [blame]

726

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

727

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

728

#

729

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

730

# the `additional_bindings` option. Example:

731

#

Jon Wayne Parrott

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

[diff] [blame]

732

# service Messaging {

733

# rpc GetMessage(GetMessageRequest) returns (Message) {

734

# option (google.api.http) = {

735

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

736

# additional_bindings {

737

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

738

# }

739

# };

Jon Wayne Parrott

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

[diff] [blame]

740

# }

Jon Wayne Parrott

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

[diff] [blame]

741

# }

742

# message GetMessageRequest {

743

# string message_id = 1;

744

# string user_id = 2;

745

# }

746

#

Bu Sun Kim

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

[diff] [blame^]

747

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

Jon Wayne Parrott

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

[diff] [blame]

748

#

Bu Sun Kim

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

[diff] [blame^]

749

# HTTP | gRPC

Jon Wayne Parrott

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

[diff] [blame]

750

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

751

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

Bu Sun Kim

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

[diff] [blame^]

752

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

753

# "123456")`

Jon Wayne Parrott

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

[diff] [blame]

754

#

Bu Sun Kim

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

[diff] [blame^]

755

# ## Rules for HTTP mapping

Jon Wayne Parrott

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

[diff] [blame]

756

#

Bu Sun Kim

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

[diff] [blame^]

757

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

758

# message) are classified into three categories:

759

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

760

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

761

# request body.

762

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

763

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

764

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

765

# name.

766

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

767

# are passed via URL path and HTTP request body.

768

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

769

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

Jon Wayne Parrott

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

[diff] [blame]

770

#

Bu Sun Kim

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

[diff] [blame^]

771

# ### Path template syntax

Jon Wayne Parrott

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

[diff] [blame]

772

#

773

# Template = "/" Segments [ Verb ] ;

774

# Segments = Segment { "/" Segment } ;

775

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

776

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

777

# FieldPath = IDENT { "." IDENT } ;

778

# Verb = ":" LITERAL ;

779

#

Bu Sun Kim

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

[diff] [blame^]

780

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

781

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

782

# except the `Verb`.

Jon Wayne Parrott

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

[diff] [blame]

783

#

Bu Sun Kim

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

[diff] [blame^]

784

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

785

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

Jon Wayne Parrott

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

[diff] [blame]

786

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

787

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

788

#

Bu Sun Kim

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

[diff] [blame^]

789

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

790

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

791

# before the matching.

Jon Wayne Parrott

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

[diff] [blame]

792

#

Bu Sun Kim

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

[diff] [blame^]

793

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

794

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

795

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

796

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

797

# [Discovery

798

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

799

# `{var}`.

800

#

801

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

802

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

803

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

804

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

805

# unchanged. Such variables show up in the

806

# [Discovery

807

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

808

# `{+var}`.

809

#

810

# ## Using gRPC API Service Configuration

811

#

812

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

813

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

814

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

815

# proto message.

816

#

817

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

818

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

819

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

820

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

821

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

822

# specified in the service config will override any matching transcoding

823

# configuration in the proto.

#

# Example:

#

# http:

# rules:

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

830

# - selector: example.v1.Messaging.GetMessage

831

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

#

# ## Special notes

#

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

836

# proto to JSON conversion must follow the [proto3

837

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

838

#

839

# While the single segment variable follows the semantics of

840

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

841

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

842

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

843

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

844

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

845

# for multi segment variables.

846

#

847

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

848

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

849

#

850

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

851

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

852

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

853

#

854

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

855

# no client library can support such complicated mapping.

856

#

857

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

858

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

859

# Transcoding implementations may not support this feature.

860

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

861

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

862

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

863

#

Bu Sun Kim

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

[diff] [blame^]

864

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

865

# message type.

Jon Wayne Parrott

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

[diff] [blame]

866

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

867

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

868

# the nesting may only be one level deep).

869

# Object with schema name: HttpRule

870

],

Bu Sun Kim

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

[diff] [blame^]

871

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

872

# resources.

873

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

874

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

875

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

876

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

877

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

Thomas Coffee

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

[diff] [blame]

878

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

879

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

880

},

Bu Sun Kim

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

[diff] [blame^]

881

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

882

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

883

# as the HTTP response body.

884

#

885

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

886

# message type.

887

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

888

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

889

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

890

#

891

# Refer to selector for syntax details.

892

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

Jon Wayne Parrott

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

[diff] [blame]

893

},

894

],

Bu Sun Kim

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

[diff] [blame^]

895

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

896

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

897

# left encoded.

898

#

899

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

900

# segment matches.

Jon Wayne Parrott

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

[diff] [blame]

901

},

902

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

903

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

904

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

905

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

906

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

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

[diff] [blame^]

907

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

908

#

909

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

910

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

911

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

912

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

913

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

914

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

915

# detailed terminology.

916

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

917

{ # Method represents a method of an API interface.

918

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

919

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

920

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

921

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

922

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

923

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

924

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

925

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

926

# enumeration, etc.

927

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

928

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

929

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

930

# `"google.api.http"`.

931

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

932

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

933

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

934

# value using the google.protobuf.Int32Value type.

935

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

},

},

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

941

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

942

# message.

943

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

944

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

945

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

946

},

Bu Sun Kim

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

[diff] [blame^]

947

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

948

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

949

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

950

# documentation and options are inherited as follows:

Jon Wayne Parrott

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

[diff] [blame]

951

#

952

# - If after comment and whitespace stripping, the documentation

953

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

954

# from the original method.

955

#

956

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

957

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

958

# inherited.

959

#

960

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

961

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

Bu Sun Kim

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

[diff] [blame^]

962

# version of the including interface plus the root path if

963

# specified.

Jon Wayne Parrott

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

[diff] [blame]

964

#

965

# Example of a simple mixin:

966

#

967

# package google.acl.v1;

968

# service AccessControl {

969

# // Get the underlying ACL object.

970

# rpc GetAcl(GetAclRequest) returns (Acl) {

971

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

# }

# }

#

# package google.storage.v2;

976

# service Storage {

977

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

978

#

979

# // Get a data record.

980

# rpc GetData(GetDataRequest) returns (Data) {

981

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

# }

# }

#

# Example of a mixin configuration:

986

#

987

# apis:

988

# - name: google.storage.v2.Storage

989

# mixins:

990

# - name: google.acl.v1.AccessControl

991

#

992

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

993

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

994

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

995

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

996

# documentation and annotations as follows:

997

#

998

# service Storage {

999

# // Get the underlying ACL object.

1000

# rpc GetAcl(GetAclRequest) returns (Acl) {

1001

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

# }

# ...

# }

#

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

1007

#

1008

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

1009

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

1010

#

1011

# apis:

1012

# - name: google.storage.v2.Storage

1013

# mixins:

1014

# - name: google.acl.v1.AccessControl

1015

# root: acls

1016

#

1017

# This implies the following inherited HTTP annotation:

1018

#

1019

# service Storage {

1020

# // Get the underlying ACL object.

1021

# rpc GetAcl(GetAclRequest) returns (Acl) {

1022

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

# }

# ...

# }

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

1027

# are rooted.

Bu Sun Kim

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

[diff] [blame^]

1028

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

1029

},

1030

],

1031

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

Bu Sun Kim

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

[diff] [blame^]

1032

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

1033

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

1034

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

1035

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

1036

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

1037

# consistent with what is provided here.

Jon Wayne Parrott

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

[diff] [blame]

1038

#

1039

# The versioning schema uses [semantic

1040

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

1041

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

1042

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

1043

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

1044

# chosen based on the product plan.

1045

#

1046

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

Bu Sun Kim

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

[diff] [blame^]

1047

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

Jon Wayne Parrott

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

[diff] [blame]

1048

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

1049

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

Bu Sun Kim

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

[diff] [blame^]

1050

# experimental, non-GA interfaces.

1051

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

Jon Wayne Parrott

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

[diff] [blame]

1052

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

1053

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1054

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

1055

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

1056

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

1057

# `"google.api.http"`.

1058

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

1059

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

1060

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

1061

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1062

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

1063

},

1064

},

1065

],

Bu Sun Kim

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

[diff] [blame^]

1066

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

1067

# followed by the interface's simple name.

Jon Wayne Parrott

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

[diff] [blame]

1068

},

1069

],

1070

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

1071

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1079

# - google.foo.v1.AnotherError

1080

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

1081

#

1082

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

1083

{ # A custom error rule.

1084

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

1085

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

1086

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

1087

#

1088

# Refer to selector for syntax details.

1089

},

1090

],

1091

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

1092

"A String",

1093

],

1094

},

Sai Cheemalapati

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

[diff] [blame]

1095

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

1096

# usage.

1097

#

Bu Sun Kim

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

[diff] [blame^]

1098

# The metric based quota configuration works this way:

Sai Cheemalapati

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

[diff] [blame]

1099

# - The service configuration defines a set of metrics.

1100

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

1101

# corresponding costs.

1102

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

1103

# quota checks at runtime.

1104

#

1105

# An example quota configuration in yaml format:

1106

#

1107

# quota:

Bu Sun Kim

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

[diff] [blame^]

1108

# limits:

Sai Cheemalapati

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

[diff] [blame]

1109

#

1110

# - name: apiWriteQpsPerProject

1111

# metric: library.googleapis.com/write_calls

1112

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

# values:

# STANDARD: 10000

#

#

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

1118

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

1119

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

1120

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1125

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

1126

# metric_costs:

1127

# library.googleapis.com/write_calls: 2

1128

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

1129

# metric_costs:

1130

# library.googleapis.com/write_calls: 1

1131

#

1132

# Corresponding Metric definition:

1133

#

1134

# metrics:

1135

# - name: library.googleapis.com/read_calls

1136

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1141

# display_name: Write requests

1142

# metric_kind: DELTA

1143

# value_type: INT64

Bu Sun Kim

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

[diff] [blame^]

1144

#

Sai Cheemalapati

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

[diff] [blame]

1145

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

1146

# or more metrics.

1147

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

1148

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

1149

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

1150

# cost applied to each metric.

1151

#

1152

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

1153

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

1154

# The value must not be negative.

1155

"a_key": "A String",

1156

},

1157

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

1158

#

1159

# Refer to selector for syntax details.

1160

},

1161

],

1162

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

1163

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

1164

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

1165

# type combination defined within a `QuotaGroup`.

1166

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

1167

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

1168

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

1169

# display name generated from the configuration.

Bu Sun Kim

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

[diff] [blame^]

1170

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

1171

#

1172

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

1173

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

1174

#

1175

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

Sai Cheemalapati

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

[diff] [blame]

1176

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

1177

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

1178

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

1179

#

1180

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

1181

# are provisioning quota to selected consumers and blocking others.

1182

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

1183

# negative values are allowed.

1184

#

1185

# Used by group-based quotas only.

1186

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

1187

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

1188

# defined within the service config.

Bu Sun Kim

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

[diff] [blame^]

1189

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

1190

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

1191

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

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

[diff] [blame]

1192

"a_key": "A String",

1193

},

1194

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

1195

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

1196

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

1197

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

1198

#

1199

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

1200

# indicating unlimited maximum quota.

1201

#

1202

# Used by group-based quotas only.

1203

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

1204

# For duration longer than a day, only multiple of days is supported. We

1205

# support only "100s" and "1d" for now. Additional support will be added in

1206

# the future. "0" indicates indefinite duration.

1207

#

1208

# Used by group-based quotas only.

1209

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

1210

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

1211

# billed amount when billing is enabled.

1212

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

1213

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

1214

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

1215

#

1216

# Used by group-based quotas only.

1217

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

1218

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

1219

# backend system.

1220

#

Sai Cheemalapati

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

[diff] [blame]

1221

# Here are some examples:

1222

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

1223

#

1224

# Note: the order of unit components is insignificant.

1225

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

Bu Sun Kim

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

[diff] [blame^]

1226

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

1227

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

1228

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

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]

1233

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

1234

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

1235

# existing data unusable.

Bu Sun Kim

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

[diff] [blame^]

1236

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

1237

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

1238

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

Bu Sun Kim

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

[diff] [blame^]

1239

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

1240

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

1241

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

Jon Wayne Parrott

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

[diff] [blame]

1242

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

1243

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

Jon Wayne Parrott

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

[diff] [blame]

1244

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

1245

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

Jon Wayne Parrott

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

[diff] [blame]

1246

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

1247

# instance of this metric type. For example, the

1248

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

1249

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

1250

# you can look at latencies for successful responses or just

1251

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1252

{ # A description of a label.

1253

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

1254

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

1255

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

1256

},

1257

],

Bu Sun Kim

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

[diff] [blame^]

1258

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

Jon Wayne Parrott

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

[diff] [blame]

1259

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

1260

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

1261

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

1262

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1263

#

Jon Wayne Parrott

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

[diff] [blame]

1264

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

Bu Sun Kim

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

[diff] [blame^]

1265

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

Jon Wayne Parrott

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

[diff] [blame]

1266

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

Jon Wayne Parrott

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

[diff] [blame]

1267

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

1268

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

1269

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

1270

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

1271

#

1272

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

1287

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

1288

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

1289

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

1290

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

1291

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

1292

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

1293

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

1294

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

1295

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

1296

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

1297

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

1298

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

1299

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

1300

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

1301

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

1302

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

1303

#

1304

# **Grammar**

1305

#

Jon Wayne Parrott

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

[diff] [blame]

1306

# The grammar also includes these connectors:

1307

#

1308

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

1309

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

1310

#

1311

# The grammar for a unit is as follows:

1312

#

1313

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

1314

#

Bu Sun Kim

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

[diff] [blame^]

1315

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

Jon Wayne Parrott

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

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1325

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

1326

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

1327

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

1328

# containing '{' or '}'.

Bu Sun Kim

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

[diff] [blame^]

1329

# * `1` represents dimensionless value 1, such as in `1/s`.

1330

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

1331

# a percentage.

1332

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

1333

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

1334

# The launch stage of the metric definition.

1335

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

1336

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

1337

# data loss due to errors.

1338

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

1339

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

1340

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

1341

# a smaller sampling period.

1342

},

Jon Wayne Parrott

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

[diff] [blame]

1343

},

1344

],

1345

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

1346

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

1347

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

1348

# should be listed here by name. Example:

1349

#

1350

# enums:

1351

# - name: google.someapi.v1.SomeEnum

1352

{ # Enum type definition.

1353

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

1354

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

1355

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

1356

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

1357

},

Sai Cheemalapati

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

[diff] [blame]

1358

"enumvalue": [ # Enum value definitions.

1359

{ # Enum value definition.

1360

"options": [ # Protocol buffer options.

1361

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

1362

# enumeration, etc.

1363

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

1364

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

1365

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

1366

# `"google.api.http"`.

1367

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

1368

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

1369

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

1370

# value using the google.protobuf.Int32Value type.

1371

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

},

},

],

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

1376

"number": 42, # Enum value number.

1377

},

1378

],

Thomas Coffee

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

[diff] [blame]

1379

"options": [ # Protocol buffer options.

1380

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

1381

# enumeration, etc.

1382

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

1383

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

1384

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

1385

# `"google.api.http"`.

1386

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

1387

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

1388

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

1389

# value using the google.protobuf.Int32Value type.

1390

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

1395

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

Jon Wayne Parrott

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

[diff] [blame]

1396

},

1397

],

1398

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

1399

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

1400

# automatically included. Messages which are not referenced but

1401

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

1402

# should be listed here by name. Example:

1403

#

1404

# types:

1405

# - name: google.protobuf.Int32

1406

{ # A protocol buffer message type.

1407

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

1408

"A String",

1409

],

1410

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

Jon Wayne Parrott

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

[diff] [blame]

1411

"fields": [ # The list of fields.

1412

{ # A single field of a message type.

1413

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

1414

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

1415

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

1416

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

1417

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

1418

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

1419

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

1420

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

1421

"number": 42, # The field number.

1422

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

1423

"options": [ # The protocol buffer options.

1424

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

1425

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1426

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

1427

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

1428

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

1429

# `"google.api.http"`.

1430

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

1431

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

1432

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

1433

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1434

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

},

},

],

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

1439

},

1440

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1441

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

1442

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

1443

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

1444

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

1445

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

1446

},

Jon Wayne Parrott

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

[diff] [blame]

1447

"options": [ # The protocol buffer options.

1448

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

1449

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1450

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

1451

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

1452

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

1453

# `"google.api.http"`.

1454

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

1455

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

1456

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

1457

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1458

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1464

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

Jon Wayne Parrott

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

[diff] [blame]

1465

#

1466

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

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1467

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

1468

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

1469

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

Jon Wayne Parrott

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

[diff] [blame]

1470

#

1471

# monitored_resources:

1472

# - type: library.googleapis.com/branch

1473

# labels:

1474

# - key: /city

1475

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

1476

# - key: /name

1477

# description: The name of the branch.

1478

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1479

# - name: activity_history

Jon Wayne Parrott

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

[diff] [blame]

1480

# labels:

1481

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1482

# - name: purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1483

# logging:

1484

# producer_destinations:

1485

# - monitored_resource: library.googleapis.com/branch

1486

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1487

# - activity_history

1488

# - purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1489

# consumer_destinations:

1490

# - monitored_resource: library.googleapis.com/branch

1491

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1492

# - activity_history

Jon Wayne Parrott

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

[diff] [blame]

1493

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

1494

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

1495

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

1496

# one producer destination.

1497

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

1498

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1499

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

1500

# Service.monitored_resources section.

1501

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

1502

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

1503

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

1504

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

1510

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

1511

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

1512

# one consumer destination.

1513

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

1514

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

1515

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

1516

# Service.monitored_resources section.

1517

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

1518

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

1519

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

1520

# 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^]

1526

"name": "A String", # The service name, which is a DNS-like logical identifier for the

1527

# service, such as `calendar.googleapis.com`. The service name

1528

# typically goes through DNS verification to make sure the owner

1529

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1530

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

1531

#

1532

# Example:

1533

# <pre><code>documentation:

1534

# summary: >

1535

# The Google Calendar API gives access

1536

# to most calendar features.

1537

# pages:

1538

# - name: Overview

1539

# content: (== include google/foo/overview.md ==)

1540

# - name: Tutorial

1541

# content: (== include google/foo/tutorial.md ==)

1542

# subpages;

1543

# - name: Java

1544

# content: (== include google/foo/tutorial_java.md ==)

1545

# rules:

1546

# - selector: google.calendar.Calendar.Get

1547

# description: >

1548

# ...

1549

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1554

# standard markdown features, definition lists, tables and fenced

1555

# code blocks are supported. Section headers can be provided and are

1556

# interpreted relative to the section nesting of the context where

1557

# a documentation fragment is embedded.

1558

#

1559

# Documentation from the IDL is merged with documentation defined

1560

# via the config at normalization time, where documentation provided

1561

# by config rules overrides IDL provided.

1562

#

1563

# A number of constructs specific to the API platform are supported

1564

# in documentation text.

1565

#

1566

# In order to reference a proto element, the following

1567

# notation can be used:

1568

# <pre><code>[fully.qualified.proto.name][]</code></pre>

1569

# To override the display text used for the link, this can be used:

1570

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

1571

# Text can be excluded from doc using the following notation:

1572

# <pre><code>(-- internal comment --)</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1573

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1574

# A few directives are available in documentation. Note that

1575

# directives must appear on a single line to be properly

1576

# identified. The `include` directive includes a markdown file from

1577

# an external source:

1578

# <pre><code>(== include path/to/file ==)</code></pre>

1579

# The `resource_for` directive marks a message to be the resource of

1580

# a collection in REST view. If it is not specified, tools attempt

1581

# to infer the resource from the operations in a collection:

1582

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

1583

# The directive `suppress_warning` does not directly affect documentation

1584

# and is documented together with service config validation.

1585

"rules": [ # A list of documentation rules that apply to individual API elements.

1586

#

1587

# **NOTE:** All service configuration rules follow "last one wins" order.

1588

{ # A documentation rule provides information about individual API elements.

1589

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1590

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

1591

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1592

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

1593

# qualified name of the element which may end in "*", indicating a wildcard.

1594

# 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^]

1595

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

1596

# wildcard will match one or more components. To specify a default for all

1597

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1598

},

1599

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1600

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1601

"overview": "A String", # Declares a single overview page. For example:

1602

# <pre><code>documentation:

1603

# summary: ...

1604

# overview: (== include overview.md ==)

1605

# </code></pre>

1606

# This is a shortcut for the following declaration (using pages style):

1607

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

1612

# </code></pre>

1613

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1614

"pages": [ # The top level pages for the documentation set.

1615

{ # Represents a documentation page. A page can contain subpages to represent

1616

# nested documentation set structure.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1617

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path}

1618

# ==)</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1619

"subpages": [ # Subpages of this page. The order of subpages specified here will be

1620

# honored in the generated docset.

1621

# Object with schema name: Page

1622

],

1623

"name": "A String", # The name of the page. It will be used as an identity of the page to

1624

# generate URI of the page, text of the link to this page in navigation,

1625

# etc. The full page name (start from the root page name to this page

1626

# concatenated with `.`) can be used as reference to the page in your

1627

# documentation. For example:

1628

# <pre><code>pages:

1629

# - name: Tutorial

1630

# content: (== include tutorial.md ==)

1631

# subpages:

1632

# - name: Java

1633

# content: (== include tutorial_java.md ==)

1634

# </code></pre>

1635

# You can reference `Java` page using Markdown reference link syntax:

1636

# `Java`.

1637

},

1638

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1639

"summary": "A String", # A short summary of what the service does. Can only be provided by

1640

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1641

},

1642

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

1643

"sourceFiles": [ # All files used during config generation.

1644

{

1645

"a_key": "", # Properties of the object. Contains field @type with type URL.

1646

},

1647

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1648

},

1649

"systemTypes": [ # A list of all proto message types included in this API service.

1650

# It serves similar purpose as [google.api.Service.types], except that

1651

# these types are not needed by user-defined APIs. Therefore, they will not

1652

# show up in the generated discovery doc. This field should only be used

1653

# to define system APIs in ESF.

1654

{ # A protocol buffer message type.

1655

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

1656

"A String",

1657

],

1658

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1659

"fields": [ # The list of fields.

1660

{ # A single field of a message type.

1661

"kind": "A String", # The field type.

1662

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

1663

# types. The first type has index 1; zero means the type is not in the list.

1664

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

1665

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

1666

"name": "A String", # The field name.

1667

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

1668

"jsonName": "A String", # The field JSON name.

1669

"number": 42, # The field number.

1670

"cardinality": "A String", # The field cardinality.

1671

"options": [ # The protocol buffer options.

1672

{ # A protocol buffer option, which can be attached to a message, field,

1673

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1674

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1675

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1676

# For custom options, it should be the fully-qualified name. For example,

1677

# `"google.api.http"`.

1678

"value": { # The option's value packed in an Any message. If the value is a primitive,

1679

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1680

# should be used. If the value is an enum, it should be stored as an int32

1681

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1682

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

1687

},

1688

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1689

"syntax": "A String", # The source syntax.

1690

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

1691

# protobuf element, like the file in which it is defined.

1692

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

1693

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

1694

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1695

"options": [ # The protocol buffer options.

1696

{ # A protocol buffer option, which can be attached to a message, field,

1697

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1698

"name": "A String", # The option's name. For protobuf built-in options (options defined in

1699

# descriptor.proto), this is the short name. For example, `"map_entry"`.

1700

# For custom options, it should be the fully-qualified name. For example,

1701

# `"google.api.http"`.

1702

"value": { # The option's value packed in an Any message. If the value is a primitive,

1703

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1704

# should be used. If the value is an enum, it should be stored as an int32

1705

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1706

"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

1721

# - google.rpc.context.OriginContext

1722

#

1723

# The above specifies that all methods in the API request

1724

# `google.rpc.context.ProjectContext` and

1725

# `google.rpc.context.OriginContext`.

1726

#

1727

# Available context types are defined in package

1728

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1729

#

1730

# This also provides mechanism to whitelist any protobuf message extension that

1731

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

1732

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

1733

# 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"

1741

# allowed_request_extensions:

1742

# - google.foo.v1.NewExtension

1743

# allowed_response_extensions:

1744

# - google.foo.v1.NewExtension

1745

#

1746

# You can also specify extension ID instead of fully qualified extension name

1747

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1748

"rules": [ # A list of RPC context rules that apply to individual API methods.

1749

#

1750

# **NOTE:** All service configuration rules follow "last one wins" order.

1751

{ # A context rule provides information about the context for an individual API

1752

# element.

1753

"provided": [ # A list of full type names of provided contexts.

1754

"A String",

1755

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1756

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1757

# side channel from backend to client.

1758

"A String",

1759

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1760

"selector": "A String", # Selects the methods to which this rule applies.

1761

#

1762

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1763

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

1764

# side channel from client to backend.

1765

"A String",

1766

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1767

"requested": [ # A list of full type names of requested contexts.

1768

"A String",

1769

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1770

},

1771

],

1772

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1773

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

1774

# with the same name as the service is automatically generated to service all

1775

# defined APIs.

1776

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

1777

# A service may expose any number of endpoints, and all endpoints share the

1778

# same service configuration, such as quota configuration and monitoring

1779

# configuration.

1780

#

1781

# Example service configuration:

1782

#

1783

# name: library-example.googleapis.com

1784

# endpoints:

1785

# # Below entry makes 'google.example.library.v1.Library'

1786

# # API be served from endpoint address library-example.googleapis.com.

1787

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

1788

# # it to decide whether the subsequent cross-origin request is

1789

# # allowed to proceed.

1790

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1791

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1792

"allowCors": True or False, # Allowing

1793

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

1794

# cross-domain traffic, would allow the backends served from this endpoint to

1795

# receive and respond to HTTP OPTIONS requests. The response will be used by

1796

# the browser to determine whether the subsequent cross-origin request is

1797

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1798

"target": "A String", # The specification of an Internet routable address of API frontend that will

1799

# handle requests to this [API

1800

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

1801

# either a valid IPv4 address or a fully-qualified domain name. For example,

1802

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1803

"features": [ # The list of features enabled on this endpoint.

1804

"A String",

1805

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1806

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1807

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1808

# please specify multiple google.api.Endpoint for each of the intended

1809

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1810

#

1811

# 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]

1816

}

1817

1818

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1825

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1826

{ # `Service` is the root object of Google service configuration schema. It

1827

# describes basic information about a service, such as the name and the

1828

# title, and delegates other aspects to sub-sections. Each sub-section is

1829

# either a proto message or a repeated proto message that configures a

1830

# 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]

1835

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1836

# name: calendar.googleapis.com

1837

# title: Google Calendar API

1838

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1839

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1840

# authentication:

1841

# providers:

1842

# - id: google_calendar_auth

1843

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

1844

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1845

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1846

# - selector: "*"

1847

# requirements:

1848

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1849

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

1850

# service controller handles features like abuse, quota, billing, logging,

1851

# monitoring, etc.

1852

"environment": "A String", # The service control environment to use. If empty, no control plane

1853

# feature (like quota and billing) will be enabled.

1854

},

1855

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

1856

# by the Service.monitoring and Service.logging configurations.

1857

{ # An object that describes the schema of a MonitoredResource object using a

1858

# type name and a set of labels. For example, the monitored resource

1859

# descriptor for Google Compute Engine VM instances has a type of

1860

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

1861

# `"zone"` to identify particular VM instances.

1862

#

1863

# Different APIs can support different monitored resource types. APIs generally

1864

# provide a `list` method that returns the monitored resource descriptors used

1865

# by the API.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1866

#

1867

# Next ID: 10

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1868

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

1869

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

1870

# without any article or other determiners. For example,

1871

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1872

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

1873

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

1874

# {type} is the value of the `type` field in this object and

1875

# {project_id} is a project ID that provides API-specific context for

1876

# accessing the type. APIs that do not use project information can use the

1877

# resource name format `"monitoredResourceDescriptors/{type}"`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1878

"labels": [ # Required. A set of labels used to describe instances of this monitored

1879

# resource type. For example, an individual Google Cloud SQL database is

1880

# identified by values for the labels `"database_id"` and `"zone"`.

1881

{ # A description of a label.

1882

"valueType": "A String", # The type of data that can be assigned to the label.

1883

"description": "A String", # A human-readable description for the label.

1884

"key": "A String", # The label key.

1885

},

1886

],

1887

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

1888

"type": "A String", # Required. The monitored resource type. For example, the type

1889

# `"cloudsql_database"` represents databases in Google Cloud SQL.

1890

# The maximum length of this value is 256 characters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1891

"description": "A String", # Optional. A detailed description of the monitored resource type that might

1892

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1893

},

1894

],

1895

"logs": [ # Defines the logs used by this service.

1896

{ # A description of a log type. Example in YAML format:

1897

#

1898

# - name: library.googleapis.com/activity_history

1899

# description: The history of borrowing and returning library items.

1900

# display_name: Activity

1901

# labels:

1902

# - key: /customer_id

1903

# description: Identifier of a library customer

1904

"labels": [ # The set of labels that are available to describe a specific log entry.

1905

# Runtime requests that contain labels not specified here are

1906

# considered invalid.

1907

{ # A description of a label.

1908

"valueType": "A String", # The type of data that can be assigned to the label.

1909

"description": "A String", # A human-readable description for the label.

1910

"key": "A String", # The label key.

1911

},

1912

],

1913

"displayName": "A String", # The human-readable name for this log. This information appears on

1914

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1915

"name": "A String", # The name of the log. It must be less than 512 characters long and can

1916

# include the following characters: upper- and lower-case alphanumeric

1917

# characters [A-Za-z0-9], and punctuation characters including

1918

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1919

"description": "A String", # A human-readable description of this log. This information appears in

1920

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1921

},

1922

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1923

"systemParameters": { # ### System parameter configuration # System parameter configuration.

1924

#

1925

# A system parameter is a special kind of parameter defined by the API

1926

# system, not by an individual API. It is typically mapped to an HTTP header

1927

# and/or a URL query parameter. This configuration specifies which methods

1928

# change the names of the system parameters.

1929

"rules": [ # Define system parameters.

1930

#

1931

# The parameters defined here will override the default parameters

1932

# implemented by the system. If this field is missing from the service

1933

# config, default system parameters will be used. Default system parameters

1934

# and names is implementation-dependent.

1935

#

1936

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1944

#

1945

#

1946

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1951

# parameters:

1952

# - name: api_key

1953

# http_header: Api-Key1

1954

# - name: api_key

1955

# http_header: Api-Key2

1956

#

1957

# **NOTE:** All service configuration rules follow "last one wins" order.

1958

{ # Define a system parameter rule mapping system parameter definitions to

1959

# methods.

1960

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

1961

# For a given method call, only one of them should be used. If multiple

1962

# names are used the behavior is implementation-dependent.

1963

# If none of the specified names are present the behavior is

1964

# parameter-dependent.

1965

{ # Define a parameter's name and location. The parameter may be passed as either

1966

# an HTTP header or a URL query parameter, and if both are passed the behavior

1967

# is implementation-dependent.

1968

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

1969

# sensitive.

1970

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

1971

# insensitive.

1972

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

1973

},

1974

],

1975

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1976

# methods in all APIs.

1977

#

1978

# Refer to selector for syntax details.

1979

},

1980

],

1981

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

1982

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

1983

# by the client for tracking purpose. If empty, the server may choose to

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1984

# generate one instead. Must be no longer than 60 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1985

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

1986

"rules": [ # A list of API backend rules that apply to individual API methods.

1987

#

1988

# **NOTE:** All service configuration rules follow "last one wins" order.

1989

{ # A backend rule provides configuration for an individual API element.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1990

"jwtAudience": "A String", # The JWT audience is used when generating a JWT id token for the backend.

1991

"pathTranslation": "A String",

1992

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

1993

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1994

"selector": "A String", # Selects the methods to which this rule applies.

1995

#

1996

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

1997

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

1998

# operation. The default is no deadline.

1999

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

2000

# deadline for gRPC is infinite (no deadline) and HTTP requests is 5 seconds.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2001

"address": "A String", # The address of the API backend.

2002

},

2003

],

2004

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2005

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2006

#

2007

# The example below shows how to configure monitored resources and metrics

2008

# for monitoring. In the example, a monitored resource and two metrics are

2009

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2010

# to both producer and consumer projects, whereas the

2011

# `library.googleapis.com/book/overdue_count` metric is only sent to the

2012

# consumer project.

2013

#

2014

# monitored_resources:

2015

# - type: library.googleapis.com/branch

2016

# labels:

2017

# - key: /city

2018

# description: The city where the library branch is located in.

2019

# - key: /name

2020

# description: The name of the branch.

2021

# metrics:

2022

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2027

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2032

# monitoring:

2033

# producer_destinations:

2034

# - monitored_resource: library.googleapis.com/branch

2035

# metrics:

2036

# - library.googleapis.com/book/returned_count

2037

# consumer_destinations:

2038

# - monitored_resource: library.googleapis.com/branch

2039

# metrics:

2040

# - library.googleapis.com/book/returned_count

2041

# - library.googleapis.com/book/overdue_count

2042

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2043

# There can be multiple producer destinations. A monitored resouce type may

2044

# appear in multiple monitoring destinations if different aggregations are

2045

# needed for different sets of metrics associated with that monitored

2046

# resource type. A monitored resource and metric pair may only be used once

2047

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2048

{ # Configuration of a specific monitoring destination (the producer project

2049

# or the consumer project).

2050

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2051

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2052

"metrics": [ # Types of the metrics to report to this monitoring destination.

2053

# 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^]

2059

# There can be multiple consumer destinations. A monitored resouce type may

2060

# appear in multiple monitoring destinations if different aggregations are

2061

# needed for different sets of metrics associated with that monitored

2062

# resource type. A monitored resource and metric pair may only be used once

2063

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2064

{ # Configuration of a specific monitoring destination (the producer project

2065

# or the consumer project).

2066

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2067

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2068

"metrics": [ # Types of the metrics to report to this monitoring destination.

2069

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

2076

#

2077

# The following example shows how to configure monitored resources and metrics

2078

# for billing:

2079

#

2080

# monitored_resources:

2081

# - type: library.googleapis.com/branch

2082

# labels:

2083

# - key: /city

2084

# description: The city where the library branch is located in.

2085

# - key: /name

2086

# description: The name of the branch.

2087

# metrics:

2088

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

2093

# - monitored_resource: library.googleapis.com/branch

2094

# metrics:

2095

# - library.googleapis.com/book/borrowed_count

2096

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

2097

# There can be multiple consumer destinations per service, each one must have

2098

# a different monitored resource type. A metric can be used in at most

2099

# one consumer destination.

2100

{ # Configuration of a specific billing destination (Currently only support

2101

# bill against consumer project).

2102

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2103

# Service.monitored_resources section.

2104

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2105

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2111

"title": "A String", # The product title for this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2112

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

2113

#

2114

# Example for an API targeted for external use:

2115

#

2116

# name: calendar.googleapis.com

2117

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2118

# providers:

2119

# - id: google_calendar_auth

2120

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2121

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2122

# rules:

2123

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2124

# requirements:

2125

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2126

"rules": [ # A list of authentication rules that apply to individual API methods.

2127

#

2128

# **NOTE:** All service configuration rules follow "last one wins" order.

2129

{ # Authentication rules for the service.

2130

#

2131

# By default, if a method has any authentication requirements, every request

2132

# must include a valid credential matching one of the requirements.

2133

# It's an error to include more than one kind of credential in a single

2134

# request.

2135

#

2136

# If a method doesn't have any auth requirements, request credentials will be

2137

# ignored.

2138

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

2139

# there are scopes defined for "Read-only access to Google Calendar" and

2140

# "Access to Cloud Platform". Users can consent to a scope for an application,

2141

# giving it permission to access that data on their behalf.

2142

#

2143

# OAuth scope specifications should be fairly coarse grained; a user will need

2144

# to see and understand the text description of what your scope means.

2145

#

2146

# In most cases: use one or at most two OAuth scopes for an entire family of

2147

# products. If your product has multiple APIs, you should probably be sharing

2148

# the OAuth scope across all of those APIs.

2149

#

2150

# When you need finer grained OAuth consent screens: talk with your product

2151

# management about how developers will use them in practice.

2152

#

2153

# Please note that even though each of the canonical scopes is enough for a

2154

# request to be accepted and passed to the backend, a request can still fail

2155

# due to the backend requiring additional scopes or permissions.

2156

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

2157

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

2162

# https://www.googleapis.com/auth/calendar.read

2163

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2164

"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]

2165

"requirements": [ # Requirements for additional authentication providers.

2166

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2167

# [JSON Web Token

2168

# (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]

2169

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2174

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

2175

# implemented and accepted in all the runtime components.

2176

#

2177

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2178

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2179

# that are allowed to access. A JWT containing any of these audiences will

2180

# be accepted. When this setting is absent, only JWTs with audience

2181

# "https://Service_name/API_name"

2182

# will be accepted. For example, if no audiences are in the setting,

2183

# LibraryService API will only accept JWTs with the following audience

2184

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2189

# bookstore_web.apps.googleusercontent.com

2190

},

2191

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2192

"selector": "A String", # Selects the methods to which this rule applies.

2193

#

2194

# Refer to selector for syntax details.

2195

},

2196

],

2197

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2198

{ # Configuration for an authentication provider, including support for

2199

# [JSON Web Token

2200

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

2201

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

2202

# [OpenID

2203

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

2204

# Optional if the key set document:

2205

# - can be retrieved from

2206

# [OpenID

2207

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

2208

# the issuer.

2209

# - can be inferred from the email domain of the issuer (e.g. a Google

2210

# service account).

2211

#

2212

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2213

"audiences": "A String", # The list of JWT

2214

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2215

# that are allowed to access. A JWT containing any of these audiences will

2216

# be accepted. When this setting is absent, only JWTs with audience

2217

# "https://Service_name/API_name"

2218

# will be accepted. For example, if no audiences are in the setting,

2219

# LibraryService API will only accept JWTs with the following audience

2220

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2225

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2226

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

2227

# `AuthRequirement.provider_id`.

2228

#

2229

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2230

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

2231

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2232

"issuer": "A String", # Identifies the principal that issued the JWT. See

2233

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

2234

# Usually a URL or an email address.

2235

#

2236

# Example: https://securetoken.google.com

2237

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

2242

"rules": [ # A list of usage rules that apply to individual API methods.

2243

#

2244

# **NOTE:** All service configuration rules follow "last one wins" order.

2245

{ # Usage configuration rules for the service.

2246

#

2247

# NOTE: Under development.

2248

#

2249

#

2250

# Use this rule to configure unregistered calls for the service. Unregistered

2251

# calls are calls that do not contain consumer project identity.

2252

# (Example: calls that do not contain an API key).

2253

# By default, API methods do not allow unregistered calls, and each method call

2254

# must be identified by a consumer project identity. Use this rule to

2255

# allow/disallow unregistered calls.

2256

#

2257

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

2263

#

2264

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

2269

# allow_unregistered_calls: true

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2270

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

2271

# plane features, such as quota and billing, will not be available.

2272

# This flag is used by Google Cloud Endpoints to bypass checks for internal

2273

# methods, such as service health check methods.

2274

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

2275

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2276

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2277

# methods in all APIs.

2278

#

2279

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2280

},

2281

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2282

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

2283

# service producer.

2284

#

2285

# Google Service Management currently only supports

2286

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2287

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2288

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2289

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2290

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

2291

# service. Each requirement is of the form <service.name>/<requirement-id>;

2292

# for example 'serviceusage.googleapis.com/billing-enabled'.

2293

"A String",

2294

],

2295

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2296

"configVersion": 42, # The semantic version of the service configuration. The config version

2297

# affects the interpretation of the service configuration. For example,

2298

# certain features are enabled by default for certain config versions.

2299

# The latest config version is `3`.

2300

"producerProjectId": "A String", # The Google project that owns this service.

2301

"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]

2302

# HttpRule, each specifying the mapping of an RPC method

2303

# to one or more HTTP REST API methods.

2304

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2305

#

2306

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2307

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2308

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2309

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

2310

# more HTTP REST endpoints. It allows developers to build a single API service

2311

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

2312

# APIs](https://github.com/googleapis/googleapis),

2313

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

2314

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

2315

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

2316

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2317

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2318

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

2319

# how different portions of the gRPC request message are mapped to the URL

2320

# path, URL query parameters, and HTTP request body. It also controls how the

2321

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

2322

# typically specified as an `google.api.http` annotation on the gRPC method.

2323

#

2324

# Each mapping specifies a URL path template and an HTTP method. The path

2325

# template may refer to one or more fields in the gRPC request message, as long

2326

# as each field is a non-repeated field with a primitive (non-message) type.

2327

# The path template controls how fields of the request message are mapped to

2328

# the URL path.

2329

#

2330

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2331

#

2332

# service Messaging {

2333

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2334

# option (google.api.http) = {

2335

# get: "/v1/{name=messages/*}"

2336

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2337

# }

2338

# }

2339

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2340

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2341

# }

2342

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2343

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2344

# }

2345

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2346

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2347

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2348

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2349

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2350

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2351

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2352

# Any fields in the request message which are not bound by the path template

2353

# automatically become HTTP query parameters if there is no HTTP request body.

2354

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2355

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2356

# service Messaging {

2357

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2358

# option (google.api.http) = {

2359

# get:"/v1/messages/{message_id}"

2360

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2361

# }

2362

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2363

# message GetMessageRequest {

2364

# message SubMessage {

2365

# string subfield = 1;

2366

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2367

# string message_id = 1; // Mapped to URL path.

2368

# int64 revision = 2; // Mapped to URL query parameter `revision`.

2369

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2370

# }

2371

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2372

# This enables a HTTP JSON to RPC mapping as below:

2373

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2374

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2375

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2376

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

2377

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

2378

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2379

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2380

# Note that fields which are mapped to URL query parameters must have a

2381

# primitive type or a repeated primitive type or a non-repeated message type.

2382

# In the case of a repeated type, the parameter can be repeated in the URL

2383

# as `...?param=A&param=B`. In the case of a message type, each field of the

2384

# message is mapped to a separate parameter, such as

2385

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2386

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2387

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2388

# specifies the mapping. Consider a REST update method on the

2389

# message resource collection:

2390

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2391

# service Messaging {

2392

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2393

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2394

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2400

# string message_id = 1; // mapped to the URL

2401

# Message message = 2; // mapped to the body

2402

# }

2403

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2404

# The following HTTP JSON to RPC mapping is enabled, where the

2405

# representation of the JSON in the request body is determined by

2406

# protos JSON encoding:

2407

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2408

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2409

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2410

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2411

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2412

#

2413

# The special name `*` can be used in the body mapping to define that

2414

# every field not bound by the path template should be mapped to the

2415

# request body. This enables the following alternative definition of

2416

# the update method:

2417

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2418

# service Messaging {

2419

# rpc UpdateMessage(Message) returns (Message) {

2420

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2421

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

2428

# string text = 2;

2429

# }

2430

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2431

#

2432

# The following HTTP JSON to RPC mapping is enabled:

2433

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2434

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2435

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2436

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

2437

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2438

#

2439

# Note that when using `*` in the body mapping, it is not possible to

2440

# 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^]

2441

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2442

# defining REST APIs. The common usage of `*` is in custom methods

2443

# which don't use the URL at all for transferring data.

2444

#

2445

# It is possible to define multiple HTTP methods for one RPC by using

2446

# the `additional_bindings` option. Example:

2447

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2448

# service Messaging {

2449

# rpc GetMessage(GetMessageRequest) returns (Message) {

2450

# option (google.api.http) = {

2451

# get: "/v1/messages/{message_id}"

2452

# additional_bindings {

2453

# get: "/v1/users/{user_id}/messages/{message_id}"

2454

# }

2455

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2456

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2457

# }

2458

# message GetMessageRequest {

2459

# string message_id = 1;

2460

# string user_id = 2;

2461

# }

2462

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2463

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2464

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2465

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2466

# -----|-----

2467

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2468

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

2469

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2470

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2471

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2472

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2473

# 1. Leaf request fields (recursive expansion nested messages in the request

2474

# message) are classified into three categories:

2475

# - Fields referred by the path template. They are passed via the URL path.

2476

# - Fields referred by the HttpRule.body. They are passed via the HTTP

2477

# request body.

2478

# - All other fields are passed via the URL query parameters, and the

2479

# parameter name is the field path in the request message. A repeated

2480

# field can be represented as multiple query parameters under the same

2481

# name.

2482

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

2483

# are passed via URL path and HTTP request body.

2484

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

2485

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2486

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2487

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2488

#

2489

# Template = "/" Segments [ Verb ] ;

2490

# Segments = Segment { "/" Segment } ;

2491

# Segment = "*" | "**" | LITERAL | Variable ;

2492

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2493

# FieldPath = IDENT { "." IDENT } ;

2494

# Verb = ":" LITERAL ;

2495

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2496

# The syntax `*` matches a single URL path segment. The syntax `**` matches

2497

# zero or more URL path segments, which must be the last part of the URL path

2498

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2499

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2500

# The syntax `Variable` matches part of the URL path as specified by its

2501

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2502

# matches a single path segment, its template may be omitted, e.g. `{var}`

2503

# is equivalent to `{var=*}`.

2504

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2505

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

2506

# contains any reserved character, such characters should be percent-encoded

2507

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2508

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2509

# If a variable contains exactly one path segment, such as `"{var}"` or

2510

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

2511

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

2512

# server side does the reverse decoding. Such variables show up in the

2513

# [Discovery

2514

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2515

# `{var}`.

2516

#

2517

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

2518

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

2519

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

2520

# The server side does the reverse decoding, except "%2F" and "%2f" are left

2521

# unchanged. Such variables show up in the

2522

# [Discovery

2523

# Document](https://developers.google.com/discovery/v1/reference/apis) as

2524

# `{+var}`.

2525

#

2526

# ## Using gRPC API Service Configuration

2527

#

2528

# gRPC API Service Configuration (service config) is a configuration language

2529

# for configuring a gRPC service to become a user-facing product. The

2530

# service config is simply the YAML representation of the `google.api.Service`

2531

# proto message.

2532

#

2533

# As an alternative to annotating your proto file, you can configure gRPC

2534

# transcoding in your service config YAML files. You do this by specifying a

2535

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

2536

# effect as the proto annotation. This can be particularly useful if you

2537

# have a proto that is reused in multiple services. Note that any transcoding

2538

# specified in the service config will override any matching transcoding

2539

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

2546

# - selector: example.v1.Messaging.GetMessage

2547

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

2552

# proto to JSON conversion must follow the [proto3

2553

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

2554

#

2555

# While the single segment variable follows the semantics of

2556

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2557

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

2558

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

2559

# does not expand special characters like `?` and `#`, which would lead

2560

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

2561

# for multi segment variables.

2562

#

2563

# The path variables **must not** refer to any repeated or mapped field,

2564

# because client libraries are not capable of handling such variable expansion.

2565

#

2566

# The path variables **must not** capture the leading "/" character. The reason

2567

# is that the most common use case "{var}" does not capture the leading "/"

2568

# character. For consistency, all path variables must share the same behavior.

2569

#

2570

# Repeated message fields must not be mapped to URL query parameters, because

2571

# no client library can support such complicated mapping.

2572

#

2573

# If an API needs to use a JSON array for request or response body, it can map

2574

# the request or response body to a repeated field. However, some gRPC

2575

# Transcoding implementations may not support this feature.

2576

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

2577

# body, or `*` for mapping all request fields not captured by the path

2578

# 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]

2579

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2580

# NOTE: the referred field must be present at the top-level of the request

2581

# message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2582

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2583

# not contain an `additional_bindings` field themselves (that is,

2584

# the nesting may only be one level deep).

2585

# Object with schema name: HttpRule

2586

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2587

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

2588

# resources.

2589

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

2590

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

2591

# included in the `pattern` field, such as HEAD, or "*" to leave the

2592

# HTTP method unspecified for this rule. The wild-card rule is useful

2593

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2594

"path": "A String", # The path matched by this custom verb.

2595

"kind": "A String", # The name of this custom HTTP verb.

2596

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2597

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

2598

# response body. When omitted, the entire response message will be used

2599

# as the HTTP response body.

2600

#

2601

# NOTE: The referred field must be present at the top-level of the response

2602

# message type.

2603

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

2604

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

2605

"selector": "A String", # Selects a method to which this rule applies.

2606

#

2607

# Refer to selector for syntax details.

2608

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2609

},

2610

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2611

"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]

2612

# cases of single segment matches in reserved expansion, where "%2F" will be

2613

# left encoded.

2614

#

2615

# The default behavior is to not decode RFC 6570 reserved characters in multi

2616

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2617

},

2618

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2619

# of the google.protobuf.Api needs to be provided by the configuration

2620

# author, as the remaining fields will be derived from the IDL during the

2621

# normalization process. It is an error to specify an API interface here

2622

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2623

{ # Api is a light-weight descriptor for an API Interface.

2624

#

2625

# Interfaces are also described as "protocol buffer services" in some contexts,

2626

# such as by the "service" keyword in a .proto file, but they are different

2627

# from API Services, which represent a concrete implementation of an interface

2628

# as opposed to simply a description of methods and bindings. They are also

2629

# sometimes simply referred to as "APIs" in other contexts, such as the name of

2630

# this message itself. See https://cloud.google.com/apis/design/glossary for

2631

# detailed terminology.

2632

"methods": [ # The methods of this interface, in unspecified order.

2633

{ # Method represents a method of an API interface.

2634

"name": "A String", # The simple name of this method.

2635

"requestStreaming": True or False, # If true, the request is streamed.

2636

"responseTypeUrl": "A String", # The URL of the output message type.

2637

"requestTypeUrl": "A String", # A URL of the input message type.

2638

"responseStreaming": True or False, # If true, the response is streamed.

2639

"syntax": "A String", # The source syntax of this method.

2640

"options": [ # Any metadata attached to the method.

2641

{ # A protocol buffer option, which can be attached to a message, field,

2642

# enumeration, etc.

2643

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2644

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2645

# For custom options, it should be the fully-qualified name. For example,

2646

# `"google.api.http"`.

2647

"value": { # The option's value packed in an Any message. If the value is a primitive,

2648

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2649

# should be used. If the value is an enum, it should be stored as an int32

2650

# value using the google.protobuf.Int32Value type.

2651

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2657

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2658

# message.

2659

# protobuf element, like the file in which it is defined.

2660

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2661

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2662

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2663

"mixins": [ # Included interfaces. See Mixin.

2664

{ # Declares an API Interface to be included in this interface. The including

2665

# interface must redeclare all the methods from the included interface, but

2666

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2667

#

2668

# - If after comment and whitespace stripping, the documentation

2669

# string of the redeclared method is empty, it will be inherited

2670

# from the original method.

2671

#

2672

# - Each annotation belonging to the service config (http,

2673

# visibility) which is not set in the redeclared method will be

2674

# inherited.

2675

#

2676

# - If an http annotation is inherited, the path pattern will be

2677

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2678

# version of the including interface plus the root path if

2679

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2680

#

2681

# Example of a simple mixin:

2682

#

2683

# package google.acl.v1;

2684

# service AccessControl {

2685

# // Get the underlying ACL object.

2686

# rpc GetAcl(GetAclRequest) returns (Acl) {

2687

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2692

# service Storage {

2693

# // rpc GetAcl(GetAclRequest) returns (Acl);

2694

#

2695

# // Get a data record.

2696

# rpc GetData(GetDataRequest) returns (Data) {

2697

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2702

#

2703

# apis:

2704

# - name: google.storage.v2.Storage

2705

# mixins:

2706

# - name: google.acl.v1.AccessControl

2707

#

2708

# The mixin construct implies that all methods in `AccessControl` are

2709

# also declared with same name and request/response types in

2710

# `Storage`. A documentation generator or annotation processor will

2711

# see the effective `Storage.GetAcl` method after inherting

2712

# documentation and annotations as follows:

2713

#

2714

# service Storage {

2715

# // Get the underlying ACL object.

2716

# rpc GetAcl(GetAclRequest) returns (Acl) {

2717

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2723

#

2724

# If the `root` field in the mixin is specified, it should be a

2725

# relative path under which inherited HTTP paths are placed. Example:

2726

#

2727

# apis:

2728

# - name: google.storage.v2.Storage

2729

# mixins:

2730

# - name: google.acl.v1.AccessControl

2731

# root: acls

2732

#

2733

# This implies the following inherited HTTP annotation:

2734

#

2735

# service Storage {

2736

# // Get the underlying ACL object.

2737

# rpc GetAcl(GetAclRequest) returns (Acl) {

2738

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2743

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2744

"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]

2745

},

2746

],

2747

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2748

"version": "A String", # A version string for this interface. If specified, must have the form

2749

# `major-version.minor-version`, as in `1.10`. If the minor version is

2750

# omitted, it defaults to zero. If the entire version field is empty, the

2751

# major version is derived from the package name, as outlined below. If the

2752

# field is not empty, the version in the package name will be verified to be

2753

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2754

#

2755

# The versioning schema uses [semantic

2756

# versioning](http://semver.org) where the major version number

2757

# indicates a breaking change and the minor version an additive,

2758

# non-breaking change. Both version numbers are signals to users

2759

# what to expect from different versions, and should be carefully

2760

# chosen based on the product plan.

2761

#

2762

# The major version is also reflected in the package name of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2763

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2764

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2765

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2766

# experimental, non-GA interfaces.

2767

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2768

{ # A protocol buffer option, which can be attached to a message, field,

2769

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2770

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2771

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2772

# For custom options, it should be the fully-qualified name. For example,

2773

# `"google.api.http"`.

2774

"value": { # The option's value packed in an Any message. If the value is a primitive,

2775

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2776

# should be used. If the value is an enum, it should be stored as an int32

2777

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2778

"a_key": "", # Properties of the object. Contains field @type with type URL.

2779

},

2780

},

2781

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2782

"name": "A String", # The fully qualified name of this interface, including package name

2783

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2784

},

2785

],

2786

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2787

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2795

# - google.foo.v1.AnotherError

2796

"rules": [ # The list of custom error rules that apply to individual API messages.

2797

#

2798

# **NOTE:** All service configuration rules follow "last one wins" order.

2799

{ # A custom error rule.

2800

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2801

# objects of this type will be filtered when they appear in error payload.

2802

"selector": "A String", # Selects messages to which this rule applies.

2803

#

2804

# Refer to selector for syntax details.

2805

},

2806

],

2807

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

2808

"A String",

2809

],

2810

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2811

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

2812

# usage.

2813

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2814

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2815

# - The service configuration defines a set of metrics.

2816

# - For API calls, the quota.metric_rules maps methods to metrics with

2817

# corresponding costs.

2818

# - The quota.limits defines limits on the metrics, which will be used for

2819

# quota checks at runtime.

2820

#

2821

# An example quota configuration in yaml format:

2822

#

2823

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2824

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2825

#

2826

# - name: apiWriteQpsPerProject

2827

# metric: library.googleapis.com/write_calls

2828

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

2834

# # except for the UpdateBook and DeleteBook methods. These two methods

2835

# # are mapped to the write_calls metric, with the UpdateBook method

2836

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

2841

# - selector: google.example.library.v1.LibraryService.UpdateBook

2842

# metric_costs:

2843

# library.googleapis.com/write_calls: 2

2844

# - selector: google.example.library.v1.LibraryService.DeleteBook

2845

# metric_costs:

2846

# library.googleapis.com/write_calls: 1

2847

#

2848

# Corresponding Metric definition:

2849

#

2850

# metrics:

2851

# - name: library.googleapis.com/read_calls

2852

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

2857

# display_name: Write requests

2858

# metric_kind: DELTA

2859

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2860

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2861

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

2862

# or more metrics.

2863

{ # Bind API methods to metrics. Binding a method to a metric causes that

2864

# metric's configured quota behaviors to apply to the method call.

2865

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

2866

# cost applied to each metric.

2867

#

2868

# The key of the map is the metric name, and the values are the amount

2869

# increased for the metric against which the quota limits are defined.

2870

# The value must not be negative.

2871

"a_key": "A String",

2872

},

2873

"selector": "A String", # Selects the methods to which this rule applies.

2874

#

2875

# Refer to selector for syntax details.

2876

},

2877

],

2878

"limits": [ # List of `QuotaLimit` definitions for the service.

2879

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

2880

# for a limit type. There can be at most one limit for a duration and limit

2881

# type combination defined within a `QuotaGroup`.

2882

"displayName": "A String", # User-visible display name for this limit.

2883

# Optional. If not set, the UI will provide a default display name based on

2884

# the quota configuration. This field can be used to override the default

2885

# display name generated from the configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2886

"name": "A String", # Name of the quota limit.

2887

#

2888

# The name must be provided, and it must be unique within the service. The

2889

# name can only include alphanumeric characters as well as '-'.

2890

#

2891

# The maximum length of the limit name is 64 characters.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2892

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

2893

# duration. This is the number of tokens assigned when a client

2894

# application developer activates the service for his/her project.

2895

#

2896

# Specifying a value of 0 will block all requests. This can be used if you

2897

# are provisioning quota to selected consumers and blocking others.

2898

# Similarly, a value of -1 will indicate an unlimited quota. No other

2899

# negative values are allowed.

2900

#

2901

# Used by group-based quotas only.

2902

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

2903

# the same metric will be checked together during runtime. The metric must be

2904

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2905

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

2906

# integer value that is the maximum number of requests allowed for the

2907

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2908

"a_key": "A String",

2909

},

2910

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

2911

# duration. Client application developers can override the default limit up

2912

# to this maximum. If specified, this value cannot be set to a value less

2913

# than the default limit. If not specified, it is set to the default limit.

2914

#

2915

# To allow clients to apply overrides with no upper bound, set this to -1,

2916

# indicating unlimited maximum quota.

2917

#

2918

# Used by group-based quotas only.

2919

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

2920

# For duration longer than a day, only multiple of days is supported. We

2921

# support only "100s" and "1d" for now. Additional support will be added in

2922

# the future. "0" indicates indefinite duration.

2923

#

2924

# Used by group-based quotas only.

2925

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

2926

# The free tier is the number of tokens that will be subtracted from the

2927

# billed amount when billing is enabled.

2928

# This field can only be set on a limit with duration "1d", in a billable

2929

# group; it is invalid on any other limit. If this field is not set, it

2930

# defaults to 0, indicating that there is no free tier for this service.

2931

#

2932

# Used by group-based quotas only.

2933

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

2934

# Metric.unit. The supported unit kinds are determined by the quota

2935

# backend system.

2936

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2937

# Here are some examples:

2938

# * "1/min/{project}" for quota per minute per project.

2939

#

2940

# Note: the order of unit components is insignificant.

2941

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2942

"description": "A String", # Optional. User-visible, extended description for this quota limit.

2943

# Should be used only when more context is needed to understand this limit

2944

# than provided by the limit's display name (see: `display_name`).

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]

2949

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2950

# deleting or altering it stops data collection and makes the metric type's

2951

# existing data unusable.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2952

"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]

2953

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2954

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2955

# This field is optional but it is recommended to be set for any metrics

2956

# associated with user-visible concepts, such as Quota.

2957

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2958

"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]

2959

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2960

"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]

2961

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2962

"labels": [ # The set of labels that can be used to describe a specific

2963

# instance of this metric type. For example, the

2964

# `appengine.googleapis.com/http/server/response_latencies` metric

2965

# type has a label for the HTTP response code, `response_code`, so

2966

# you can look at latencies for successful responses or just

2967

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2968

{ # A description of a label.

2969

"valueType": "A String", # The type of data that can be assigned to the label.

2970

"description": "A String", # A human-readable description for the label.

2971

"key": "A String", # The label key.

2972

},

2973

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2974

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2975

"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^]

2976

# URL-encoded. All user-defined metric types have the DNS name

2977

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

2978

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2979

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2980

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

2981

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2982

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2983

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2984

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2985

# supported units are a subset of [The Unified Code for Units of

2986

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2987

#

2988

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

3003

# * `P` peta (10**15)

3004

# * `E` exa (10**18)

3005

# * `Z` zetta (10**21)

3006

# * `Y` yotta (10**24)

3007

# * `m` milli (10**-3)

3008

# * `u` micro (10**-6)

3009

# * `n` nano (10**-9)

3010

# * `p` pico (10**-12)

3011

# * `f` femto (10**-15)

3012

# * `a` atto (10**-18)

3013

# * `z` zepto (10**-21)

3014

# * `y` yocto (10**-24)

3015

# * `Ki` kibi (2**10)

3016

# * `Mi` mebi (2**20)

3017

# * `Gi` gibi (2**30)

3018

# * `Ti` tebi (2**40)

3019

#

3020

# **Grammar**

3021

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3022

# The grammar also includes these connectors:

3023

#

3024

# * `/` division (as an infix operator, e.g. `1/s`).

3025

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

3026

#

3027

# The grammar for a unit is as follows:

3028

#

3029

# Expression = Component { "." Component } { "/" Component } ;

3030

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3031

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

3041

# equivalent to `1` if it is used alone. For examples,

3042

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

3043

# * `NAME` is a sequence of non-blank printable ASCII characters not

3044

# containing '{' or '}'.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3045

# * `1` represents dimensionless value 1, such as in `1/s`.

3046

# * `%` represents dimensionless value 1/100, and annotates values giving

3047

# a percentage.

3048

"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.

3049

"launchStage": "A String", # Deprecated. Please use the MetricDescriptor.launch_stage instead.

3050

# The launch stage of the metric definition.

3051

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

3052

# age are guaranteed to be ingested and available to be read, excluding

3053

# data loss due to errors.

3054

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

3055

# periodically, consecutive data points are stored at this time interval,

3056

# excluding data loss due to errors. Metrics with a higher granularity have

3057

# a smaller sampling period.

3058

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3059

},

3060

],

3061

"enums": [ # A list of all enum types included in this API service. Enums

3062

# referenced directly or indirectly by the `apis` are automatically

3063

# included. Enums which are not referenced but shall be included

3064

# should be listed here by name. Example:

3065

#

3066

# enums:

3067

# - name: google.someapi.v1.SomeEnum

3068

{ # Enum type definition.

3069

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3070

# protobuf element, like the file in which it is defined.

3071

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3072

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3073

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3074

"enumvalue": [ # Enum value definitions.

3075

{ # Enum value definition.

3076

"options": [ # Protocol buffer options.

3077

{ # A protocol buffer option, which can be attached to a message, field,

3078

# enumeration, etc.

3079

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3080

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3081

# For custom options, it should be the fully-qualified name. For example,

3082

# `"google.api.http"`.

3083

"value": { # The option's value packed in an Any message. If the value is a primitive,

3084

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3085

# should be used. If the value is an enum, it should be stored as an int32

3086

# value using the google.protobuf.Int32Value type.

3087

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

3092

"number": 42, # Enum value number.

3093

},

3094

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3095

"options": [ # Protocol buffer options.

3096

{ # A protocol buffer option, which can be attached to a message, field,

3097

# enumeration, etc.

3098

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3099

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3100

# For custom options, it should be the fully-qualified name. For example,

3101

# `"google.api.http"`.

3102

"value": { # The option's value packed in an Any message. If the value is a primitive,

3103

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3104

# should be used. If the value is an enum, it should be stored as an int32

3105

# value using the google.protobuf.Int32Value type.

3106

"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]

3111

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3112

},

3113

],

3114

"types": [ # A list of all proto message types included in this API service.

3115

# Types referenced directly or indirectly by the `apis` are

3116

# automatically included. Messages which are not referenced but

3117

# shall be included, such as types used by the `google.protobuf.Any` type,

3118

# should be listed here by name. Example:

3119

#

3120

# types:

3121

# - name: google.protobuf.Int32

3122

{ # A protocol buffer message type.

3123

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3124

"A String",

3125

],

3126

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3127

"fields": [ # The list of fields.

3128

{ # A single field of a message type.

3129

"kind": "A String", # The field type.

3130

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3131

# types. The first type has index 1; zero means the type is not in the list.

3132

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3133

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3134

"name": "A String", # The field name.

3135

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3136

"jsonName": "A String", # The field JSON name.

3137

"number": 42, # The field number.

3138

"cardinality": "A String", # The field cardinality.

3139

"options": [ # The protocol buffer options.

3140

{ # A protocol buffer option, which can be attached to a message, field,

3141

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3142

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3143

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3144

# For custom options, it should be the fully-qualified name. For example,

3145

# `"google.api.http"`.

3146

"value": { # The option's value packed in an Any message. If the value is a primitive,

3147

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3148

# should be used. If the value is an enum, it should be stored as an int32

3149

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3150

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3155

},

3156

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3157

"syntax": "A String", # The source syntax.

3158

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3159

# protobuf element, like the file in which it is defined.

3160

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3161

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3162

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3163

"options": [ # The protocol buffer options.

3164

{ # A protocol buffer option, which can be attached to a message, field,

3165

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3166

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3167

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3168

# For custom options, it should be the fully-qualified name. For example,

3169

# `"google.api.http"`.

3170

"value": { # The option's value packed in an Any message. If the value is a primitive,

3171

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3172

# should be used. If the value is an enum, it should be stored as an int32

3173

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3174

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3180

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3181

#

3182

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3183

# producer and consumer projects. In the example, the `activity_history`

3184

# log is sent to both the producer and consumer projects, whereas the

3185

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3186

#

3187

# monitored_resources:

3188

# - type: library.googleapis.com/branch

3189

# labels:

3190

# - key: /city

3191

# description: The city where the library branch is located in.

3192

# - key: /name

3193

# description: The name of the branch.

3194

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3195

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3196

# labels:

3197

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3198

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3199

# logging:

3200

# producer_destinations:

3201

# - monitored_resource: library.googleapis.com/branch

3202

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3203

# - activity_history

3204

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3205

# consumer_destinations:

3206

# - monitored_resource: library.googleapis.com/branch

3207

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3208

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3209

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3210

# There can be multiple producer destinations, each one must have a

3211

# different monitored resource type. A log can be used in at most

3212

# one producer destination.

3213

{ # Configuration of a specific logging destination (the producer project

3214

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3215

"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]

3216

# Service.monitored_resources section.

3217

"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]

3218

# be defined in the Service.logs section. If the log name is

3219

# not a domain scoped name, it will be automatically prefixed with

3220

# 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.

3226

# There can be multiple consumer destinations, each one must have a

3227

# different monitored resource type. A log can be used in at most

3228

# one consumer destination.

3229

{ # Configuration of a specific logging destination (the producer project

3230

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3231

"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]

3232

# Service.monitored_resources section.

3233

"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]

3234

# be defined in the Service.logs section. If the log name is

3235

# not a domain scoped name, it will be automatically prefixed with

3236

# 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^]

3242

"name": "A String", # The service name, which is a DNS-like logical identifier for the

3243

# service, such as `calendar.googleapis.com`. The service name

3244

# typically goes through DNS verification to make sure the owner

3245

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3246

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

3247

#

3248

# Example:

3249

# <pre><code>documentation:

3250

# summary: >

3251

# The Google Calendar API gives access

3252

# to most calendar features.

3253

# pages:

3254

# - name: Overview

3255

# content: (== include google/foo/overview.md ==)

3256

# - name: Tutorial

3257

# content: (== include google/foo/tutorial.md ==)

3258

# subpages;

3259

# - name: Java

3260

# content: (== include google/foo/tutorial_java.md ==)

3261

# rules:

3262

# - selector: google.calendar.Calendar.Get

3263

# description: >

3264

# ...

3265

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3270

# standard markdown features, definition lists, tables and fenced

3271

# code blocks are supported. Section headers can be provided and are

3272

# interpreted relative to the section nesting of the context where

3273

# a documentation fragment is embedded.

3274

#

3275

# Documentation from the IDL is merged with documentation defined

3276

# via the config at normalization time, where documentation provided

3277

# by config rules overrides IDL provided.

3278

#

3279

# A number of constructs specific to the API platform are supported

3280

# in documentation text.

3281

#

3282

# In order to reference a proto element, the following

3283

# notation can be used:

3284

# <pre><code>[fully.qualified.proto.name][]</code></pre>

3285

# To override the display text used for the link, this can be used:

3286

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

3287

# Text can be excluded from doc using the following notation:

3288

# <pre><code>(-- internal comment --)</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3289

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3290

# A few directives are available in documentation. Note that

3291

# directives must appear on a single line to be properly

3292

# identified. The `include` directive includes a markdown file from

3293

# an external source:

3294

# <pre><code>(== include path/to/file ==)</code></pre>

3295

# The `resource_for` directive marks a message to be the resource of

3296

# a collection in REST view. If it is not specified, tools attempt

3297

# to infer the resource from the operations in a collection:

3298

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

3299

# The directive `suppress_warning` does not directly affect documentation

3300

# and is documented together with service config validation.

3301

"rules": [ # A list of documentation rules that apply to individual API elements.

3302

#

3303

# **NOTE:** All service configuration rules follow "last one wins" order.

3304

{ # A documentation rule provides information about individual API elements.

3305

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3306

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

3307

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3308

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3309

# qualified name of the element which may end in "*", indicating a wildcard.

3310

# 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^]

3311

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

3312

# wildcard will match one or more components. To specify a default for all

3313

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3314

},

3315

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3316

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3317

"overview": "A String", # Declares a single overview page. For example:

3318

# <pre><code>documentation:

3319

# summary: ...

3320

# overview: (== include overview.md ==)

3321

# </code></pre>

3322

# This is a shortcut for the following declaration (using pages style):

3323

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

3328

# </code></pre>

3329

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3330

"pages": [ # The top level pages for the documentation set.

3331

{ # Represents a documentation page. A page can contain subpages to represent

3332

# nested documentation set structure.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3333

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path}

3334

# ==)</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3335

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3336

# honored in the generated docset.

3337

# Object with schema name: Page

3338

],

3339

"name": "A String", # The name of the page. It will be used as an identity of the page to

3340

# generate URI of the page, text of the link to this page in navigation,

3341

# etc. The full page name (start from the root page name to this page

3342

# concatenated with `.`) can be used as reference to the page in your

3343

# documentation. For example:

3344

# <pre><code>pages:

3345

# - name: Tutorial

3346

# content: (== include tutorial.md ==)

3347

# subpages:

3348

# - name: Java

3349

# content: (== include tutorial_java.md ==)

3350

# </code></pre>

3351

# You can reference `Java` page using Markdown reference link syntax:

3352

# `Java`.

3353

},

3354

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3355

"summary": "A String", # A short summary of what the service does. Can only be provided by

3356

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3357

},

3358

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

3359

"sourceFiles": [ # All files used during config generation.

3360

{

3361

"a_key": "", # Properties of the object. Contains field @type with type URL.

3362

},

3363

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3364

},

3365

"systemTypes": [ # A list of all proto message types included in this API service.

3366

# It serves similar purpose as [google.api.Service.types], except that

3367

# these types are not needed by user-defined APIs. Therefore, they will not

3368

# show up in the generated discovery doc. This field should only be used

3369

# to define system APIs in ESF.

3370

{ # A protocol buffer message type.

3371

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3372

"A String",

3373

],

3374

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3375

"fields": [ # The list of fields.

3376

{ # A single field of a message type.

3377

"kind": "A String", # The field type.

3378

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3379

# types. The first type has index 1; zero means the type is not in the list.

3380

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3381

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3382

"name": "A String", # The field name.

3383

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3384

"jsonName": "A String", # The field JSON name.

3385

"number": 42, # The field number.

3386

"cardinality": "A String", # The field cardinality.

3387

"options": [ # The protocol buffer options.

3388

{ # A protocol buffer option, which can be attached to a message, field,

3389

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3390

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3391

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3392

# For custom options, it should be the fully-qualified name. For example,

3393

# `"google.api.http"`.

3394

"value": { # The option's value packed in an Any message. If the value is a primitive,

3395

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3396

# should be used. If the value is an enum, it should be stored as an int32

3397

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3398

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3403

},

3404

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3405

"syntax": "A String", # The source syntax.

3406

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3407

# protobuf element, like the file in which it is defined.

3408

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3409

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3410

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3411

"options": [ # The protocol buffer options.

3412

{ # A protocol buffer option, which can be attached to a message, field,

3413

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3414

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3415

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3416

# For custom options, it should be the fully-qualified name. For example,

3417

# `"google.api.http"`.

3418

"value": { # The option's value packed in an Any message. If the value is a primitive,

3419

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3420

# should be used. If the value is an enum, it should be stored as an int32

3421

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3422

"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

3437

# - google.rpc.context.OriginContext

3438

#

3439

# The above specifies that all methods in the API request

3440

# `google.rpc.context.ProjectContext` and

3441

# `google.rpc.context.OriginContext`.

3442

#

3443

# Available context types are defined in package

3444

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3445

#

3446

# This also provides mechanism to whitelist any protobuf message extension that

3447

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

3448

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

3449

# 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"

3457

# allowed_request_extensions:

3458

# - google.foo.v1.NewExtension

3459

# allowed_response_extensions:

3460

# - google.foo.v1.NewExtension

3461

#

3462

# You can also specify extension ID instead of fully qualified extension name

3463

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3464

"rules": [ # A list of RPC context rules that apply to individual API methods.

3465

#

3466

# **NOTE:** All service configuration rules follow "last one wins" order.

3467

{ # A context rule provides information about the context for an individual API

3468

# element.

3469

"provided": [ # A list of full type names of provided contexts.

3470

"A String",

3471

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3472

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3473

# side channel from backend to client.

3474

"A String",

3475

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3476

"selector": "A String", # Selects the methods to which this rule applies.

3477

#

3478

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3479

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

3480

# side channel from client to backend.

3481

"A String",

3482

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3483

"requested": [ # A list of full type names of requested contexts.

3484

"A String",

3485

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3486

},

3487

],

3488

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3489

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

3490

# with the same name as the service is automatically generated to service all

3491

# defined APIs.

3492

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

3493

# A service may expose any number of endpoints, and all endpoints share the

3494

# same service configuration, such as quota configuration and monitoring

3495

# configuration.

3496

#

3497

# Example service configuration:

3498

#

3499

# name: library-example.googleapis.com

3500

# endpoints:

3501

# # Below entry makes 'google.example.library.v1.Library'

3502

# # API be served from endpoint address library-example.googleapis.com.

3503

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

3504

# # it to decide whether the subsequent cross-origin request is

3505

# # allowed to proceed.

3506

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3507

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3508

"allowCors": True or False, # Allowing

3509

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

3510

# cross-domain traffic, would allow the backends served from this endpoint to

3511

# receive and respond to HTTP OPTIONS requests. The response will be used by

3512

# the browser to determine whether the subsequent cross-origin request is

3513

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3514

"target": "A String", # The specification of an Internet routable address of API frontend that will

3515

# handle requests to this [API

3516

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

3517

# either a valid IPv4 address or a fully-qualified domain name. For example,

3518

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3519

"features": [ # The list of features enabled on this endpoint.

3520

"A String",

3521

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3522

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3523

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3524

# please specify multiple google.api.Endpoint for each of the intended

3525

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3526

#

3527

# 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]

3536

<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]

3537

<pre>Gets a service configuration (version) for a managed service.

3538

3539

Args:

3540

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3541

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3542

configId: string, The id of the service configuration resource.

3543

3544

This field must be specified for the server to return all fields, including

3545

`SourceInfo`. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3546

x__xgafv: string, V1 error format.

3547

Allowed values

3548

1 - v1 error format

3549

2 - v2 error format

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3550

view: string, Specifies which parts of the Service Config should be returned in the

3551

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3552

3553

Returns:

3554

An object of the form:

3555

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3556

{ # `Service` is the root object of Google service configuration schema. It

3557

# describes basic information about a service, such as the name and the

3558

# title, and delegates other aspects to sub-sections. Each sub-section is

3559

# either a proto message or a repeated proto message that configures a

3560

# 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]

3565

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3566

# name: calendar.googleapis.com

3567

# title: Google Calendar API

3568

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3569

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3570

# authentication:

3571

# providers:

3572

# - id: google_calendar_auth

3573

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3574

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3575

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3576

# - selector: "*"

3577

# requirements:

3578

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3579

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3580

# service controller handles features like abuse, quota, billing, logging,

3581

# monitoring, etc.

3582

"environment": "A String", # The service control environment to use. If empty, no control plane

3583

# feature (like quota and billing) will be enabled.

3584

},

3585

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3586

# by the Service.monitoring and Service.logging configurations.

3587

{ # An object that describes the schema of a MonitoredResource object using a

3588

# type name and a set of labels. For example, the monitored resource

3589

# descriptor for Google Compute Engine VM instances has a type of

3590

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3591

# `"zone"` to identify particular VM instances.

3592

#

3593

# Different APIs can support different monitored resource types. APIs generally

3594

# provide a `list` method that returns the monitored resource descriptors used

3595

# by the API.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3596

#

3597

# Next ID: 10

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3598

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3599

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3600

# without any article or other determiners. For example,

3601

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3602

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3603

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3604

# {type} is the value of the `type` field in this object and

3605

# {project_id} is a project ID that provides API-specific context for

3606

# accessing the type. APIs that do not use project information can use the

3607

# resource name format `"monitoredResourceDescriptors/{type}"`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3608

"labels": [ # Required. A set of labels used to describe instances of this monitored

3609

# resource type. For example, an individual Google Cloud SQL database is

3610

# identified by values for the labels `"database_id"` and `"zone"`.

3611

{ # A description of a label.

3612

"valueType": "A String", # The type of data that can be assigned to the label.

3613

"description": "A String", # A human-readable description for the label.

3614

"key": "A String", # The label key.

3615

},

3616

],

3617

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

3618

"type": "A String", # Required. The monitored resource type. For example, the type

3619

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3620

# The maximum length of this value is 256 characters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3621

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3622

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3623

},

3624

],

3625

"logs": [ # Defines the logs used by this service.

3626

{ # A description of a log type. Example in YAML format:

3627

#

3628

# - name: library.googleapis.com/activity_history

3629

# description: The history of borrowing and returning library items.

3630

# display_name: Activity

3631

# labels:

3632

# - key: /customer_id

3633

# description: Identifier of a library customer

3634

"labels": [ # The set of labels that are available to describe a specific log entry.

3635

# Runtime requests that contain labels not specified here are

3636

# considered invalid.

3637

{ # A description of a label.

3638

"valueType": "A String", # The type of data that can be assigned to the label.

3639

"description": "A String", # A human-readable description for the label.

3640

"key": "A String", # The label key.

3641

},

3642

],

3643

"displayName": "A String", # The human-readable name for this log. This information appears on

3644

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3645

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3646

# include the following characters: upper- and lower-case alphanumeric

3647

# characters [A-Za-z0-9], and punctuation characters including

3648

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3649

"description": "A String", # A human-readable description of this log. This information appears in

3650

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3651

},

3652

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3653

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3654

#

3655

# A system parameter is a special kind of parameter defined by the API

3656

# system, not by an individual API. It is typically mapped to an HTTP header

3657

# and/or a URL query parameter. This configuration specifies which methods

3658

# change the names of the system parameters.

3659

"rules": [ # Define system parameters.

3660

#

3661

# The parameters defined here will override the default parameters

3662

# implemented by the system. If this field is missing from the service

3663

# config, default system parameters will be used. Default system parameters

3664

# and names is implementation-dependent.

3665

#

3666

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3674

#

3675

#

3676

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3681

# parameters:

3682

# - name: api_key

3683

# http_header: Api-Key1

3684

# - name: api_key

3685

# http_header: Api-Key2

3686

#

3687

# **NOTE:** All service configuration rules follow "last one wins" order.

3688

{ # Define a system parameter rule mapping system parameter definitions to

3689

# methods.

3690

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3691

# For a given method call, only one of them should be used. If multiple

3692

# names are used the behavior is implementation-dependent.

3693

# If none of the specified names are present the behavior is

3694

# parameter-dependent.

3695

{ # Define a parameter's name and location. The parameter may be passed as either

3696

# an HTTP header or a URL query parameter, and if both are passed the behavior

3697

# is implementation-dependent.

3698

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3699

# sensitive.

3700

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

3701

# insensitive.

3702

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3703

},

3704

],

3705

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3706

# methods in all APIs.

3707

#

3708

# Refer to selector for syntax details.

3709

},

3710

],

3711

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3712

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3713

# by the client for tracking purpose. If empty, the server may choose to

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3714

# generate one instead. Must be no longer than 60 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3715

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3716

"rules": [ # A list of API backend rules that apply to individual API methods.

3717

#

3718

# **NOTE:** All service configuration rules follow "last one wins" order.

3719

{ # A backend rule provides configuration for an individual API element.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3720

"jwtAudience": "A String", # The JWT audience is used when generating a JWT id token for the backend.

3721

"pathTranslation": "A String",

3722

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

3723

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3724

"selector": "A String", # Selects the methods to which this rule applies.

3725

#

3726

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3727

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

3728

# operation. The default is no deadline.

3729

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

3730

# deadline for gRPC is infinite (no deadline) and HTTP requests is 5 seconds.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3731

"address": "A String", # The address of the API backend.

3732

},

3733

],

3734

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3735

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3736

#

3737

# The example below shows how to configure monitored resources and metrics

3738

# for monitoring. In the example, a monitored resource and two metrics are

3739

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3740

# to both producer and consumer projects, whereas the

3741

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3742

# consumer project.

3743

#

3744

# monitored_resources:

3745

# - type: library.googleapis.com/branch

3746

# labels:

3747

# - key: /city

3748

# description: The city where the library branch is located in.

3749

# - key: /name

3750

# description: The name of the branch.

3751

# metrics:

3752

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3757

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3762

# monitoring:

3763

# producer_destinations:

3764

# - monitored_resource: library.googleapis.com/branch

3765

# metrics:

3766

# - library.googleapis.com/book/returned_count

3767

# consumer_destinations:

3768

# - monitored_resource: library.googleapis.com/branch

3769

# metrics:

3770

# - library.googleapis.com/book/returned_count

3771

# - library.googleapis.com/book/overdue_count

3772

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3773

# There can be multiple producer destinations. A monitored resouce type may

3774

# appear in multiple monitoring destinations if different aggregations are

3775

# needed for different sets of metrics associated with that monitored

3776

# resource type. A monitored resource and metric pair may only be used once

3777

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3778

{ # Configuration of a specific monitoring destination (the producer project

3779

# or the consumer project).

3780

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3781

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3782

"metrics": [ # Types of the metrics to report to this monitoring destination.

3783

# 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^]

3789

# There can be multiple consumer destinations. A monitored resouce type may

3790

# appear in multiple monitoring destinations if different aggregations are

3791

# needed for different sets of metrics associated with that monitored

3792

# resource type. A monitored resource and metric pair may only be used once

3793

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3794

{ # Configuration of a specific monitoring destination (the producer project

3795

# or the consumer project).

3796

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3797

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3798

"metrics": [ # Types of the metrics to report to this monitoring destination.

3799

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

3806

#

3807

# The following example shows how to configure monitored resources and metrics

3808

# for billing:

3809

#

3810

# monitored_resources:

3811

# - type: library.googleapis.com/branch

3812

# labels:

3813

# - key: /city

3814

# description: The city where the library branch is located in.

3815

# - key: /name

3816

# description: The name of the branch.

3817

# metrics:

3818

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

3823

# - monitored_resource: library.googleapis.com/branch

3824

# metrics:

3825

# - library.googleapis.com/book/borrowed_count

3826

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

3827

# There can be multiple consumer destinations per service, each one must have

3828

# a different monitored resource type. A metric can be used in at most

3829

# one consumer destination.

3830

{ # Configuration of a specific billing destination (Currently only support

3831

# bill against consumer project).

3832

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3833

# Service.monitored_resources section.

3834

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3835

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3841

"title": "A String", # The product title for this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3842

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3843

#

3844

# Example for an API targeted for external use:

3845

#

3846

# name: calendar.googleapis.com

3847

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3848

# providers:

3849

# - id: google_calendar_auth

3850

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3851

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3852

# rules:

3853

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3854

# requirements:

3855

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3856

"rules": [ # A list of authentication rules that apply to individual API methods.

3857

#

3858

# **NOTE:** All service configuration rules follow "last one wins" order.

3859

{ # Authentication rules for the service.

3860

#

3861

# By default, if a method has any authentication requirements, every request

3862

# must include a valid credential matching one of the requirements.

3863

# It's an error to include more than one kind of credential in a single

3864

# request.

3865

#

3866

# If a method doesn't have any auth requirements, request credentials will be

3867

# ignored.

3868

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3869

# there are scopes defined for "Read-only access to Google Calendar" and

3870

# "Access to Cloud Platform". Users can consent to a scope for an application,

3871

# giving it permission to access that data on their behalf.

3872

#

3873

# OAuth scope specifications should be fairly coarse grained; a user will need

3874

# to see and understand the text description of what your scope means.

3875

#

3876

# In most cases: use one or at most two OAuth scopes for an entire family of

3877

# products. If your product has multiple APIs, you should probably be sharing

3878

# the OAuth scope across all of those APIs.

3879

#

3880

# When you need finer grained OAuth consent screens: talk with your product

3881

# management about how developers will use them in practice.

3882

#

3883

# Please note that even though each of the canonical scopes is enough for a

3884

# request to be accepted and passed to the backend, a request can still fail

3885

# due to the backend requiring additional scopes or permissions.

3886

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3887

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3892

# https://www.googleapis.com/auth/calendar.read

3893

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3894

"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]

3895

"requirements": [ # Requirements for additional authentication providers.

3896

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3897

# [JSON Web Token

3898

# (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]

3899

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3904

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3905

# implemented and accepted in all the runtime components.

3906

#

3907

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3908

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3909

# that are allowed to access. A JWT containing any of these audiences will

3910

# be accepted. When this setting is absent, only JWTs with audience

3911

# "https://Service_name/API_name"

3912

# will be accepted. For example, if no audiences are in the setting,

3913

# LibraryService API will only accept JWTs with the following audience

3914

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3919

# bookstore_web.apps.googleusercontent.com

3920

},

3921

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3922

"selector": "A String", # Selects the methods to which this rule applies.

3923

#

3924

# Refer to selector for syntax details.

3925

},

3926

],

3927

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3928

{ # Configuration for an authentication provider, including support for

3929

# [JSON Web Token

3930

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3931

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3932

# [OpenID

3933

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3934

# Optional if the key set document:

3935

# - can be retrieved from

3936

# [OpenID

3937

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

3938

# the issuer.

3939

# - can be inferred from the email domain of the issuer (e.g. a Google

3940

# service account).

3941

#

3942

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3943

"audiences": "A String", # The list of JWT

3944

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3945

# that are allowed to access. A JWT containing any of these audiences will

3946

# be accepted. When this setting is absent, only JWTs with audience

3947

# "https://Service_name/API_name"

3948

# will be accepted. For example, if no audiences are in the setting,

3949

# LibraryService API will only accept JWTs with the following audience

3950

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3955

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3956

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3957

# `AuthRequirement.provider_id`.

3958

#

3959

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

3960

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

3961

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3962

"issuer": "A String", # Identifies the principal that issued the JWT. See

3963

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3964

# Usually a URL or an email address.

3965

#

3966

# Example: https://securetoken.google.com

3967

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3972

"rules": [ # A list of usage rules that apply to individual API methods.

3973

#

3974

# **NOTE:** All service configuration rules follow "last one wins" order.

3975

{ # Usage configuration rules for the service.

3976

#

3977

# NOTE: Under development.

3978

#

3979

#

3980

# Use this rule to configure unregistered calls for the service. Unregistered

3981

# calls are calls that do not contain consumer project identity.

3982

# (Example: calls that do not contain an API key).

3983

# By default, API methods do not allow unregistered calls, and each method call

3984

# must be identified by a consumer project identity. Use this rule to

3985

# allow/disallow unregistered calls.

3986

#

3987

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3993

#

3994

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3999

# allow_unregistered_calls: true

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4000

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

4001

# plane features, such as quota and billing, will not be available.

4002

# This flag is used by Google Cloud Endpoints to bypass checks for internal

4003

# methods, such as service health check methods.

4004

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

4005

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4006

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4007

# methods in all APIs.

4008

#

4009

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4010

},

4011

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4012

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4013

# service producer.

4014

#

4015

# Google Service Management currently only supports

4016

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

4017

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

4018

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

4019

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4020

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4021

# service. Each requirement is of the form <service.name>/<requirement-id>;

4022

# for example 'serviceusage.googleapis.com/billing-enabled'.

4023

"A String",

4024

],

4025

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4026

"configVersion": 42, # The semantic version of the service configuration. The config version

4027

# affects the interpretation of the service configuration. For example,

4028

# certain features are enabled by default for certain config versions.

4029

# The latest config version is `3`.

4030

"producerProjectId": "A String", # The Google project that owns this service.

4031

"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]

4032

# HttpRule, each specifying the mapping of an RPC method

4033

# to one or more HTTP REST API methods.

4034

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4035

#

4036

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4037

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4038

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4039

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

4040

# more HTTP REST endpoints. It allows developers to build a single API service

4041

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

4042

# APIs](https://github.com/googleapis/googleapis),

4043

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

4044

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

4045

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

4046

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4047

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4048

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

4049

# how different portions of the gRPC request message are mapped to the URL

4050

# path, URL query parameters, and HTTP request body. It also controls how the

4051

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

4052

# typically specified as an `google.api.http` annotation on the gRPC method.

4053

#

4054

# Each mapping specifies a URL path template and an HTTP method. The path

4055

# template may refer to one or more fields in the gRPC request message, as long

4056

# as each field is a non-repeated field with a primitive (non-message) type.

4057

# The path template controls how fields of the request message are mapped to

4058

# the URL path.

4059

#

4060

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4061

#

4062

# service Messaging {

4063

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4064

# option (google.api.http) = {

4065

# get: "/v1/{name=messages/*}"

4066

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4067

# }

4068

# }

4069

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4070

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4071

# }

4072

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4073

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4074

# }

4075

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4076

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4077

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4078

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4079

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4080

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4081

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4082

# Any fields in the request message which are not bound by the path template

4083

# automatically become HTTP query parameters if there is no HTTP request body.

4084

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4085

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4086

# service Messaging {

4087

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4088

# option (google.api.http) = {

4089

# get:"/v1/messages/{message_id}"

4090

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4091

# }

4092

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4093

# message GetMessageRequest {

4094

# message SubMessage {

4095

# string subfield = 1;

4096

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4097

# string message_id = 1; // Mapped to URL path.

4098

# int64 revision = 2; // Mapped to URL query parameter `revision`.

4099

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4100

# }

4101

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4102

# This enables a HTTP JSON to RPC mapping as below:

4103

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4104

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4105

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4106

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

4107

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

4108

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4109

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4110

# Note that fields which are mapped to URL query parameters must have a

4111

# primitive type or a repeated primitive type or a non-repeated message type.

4112

# In the case of a repeated type, the parameter can be repeated in the URL

4113

# as `...?param=A&param=B`. In the case of a message type, each field of the

4114

# message is mapped to a separate parameter, such as

4115

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4116

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4117

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4118

# specifies the mapping. Consider a REST update method on the

4119

# message resource collection:

4120

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4121

# service Messaging {

4122

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4123

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4124

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4130

# string message_id = 1; // mapped to the URL

4131

# Message message = 2; // mapped to the body

4132

# }

4133

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4134

# The following HTTP JSON to RPC mapping is enabled, where the

4135

# representation of the JSON in the request body is determined by

4136

# protos JSON encoding:

4137

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4138

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4139

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4140

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4141

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4142

#

4143

# The special name `*` can be used in the body mapping to define that

4144

# every field not bound by the path template should be mapped to the

4145

# request body. This enables the following alternative definition of

4146

# the update method:

4147

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4148

# service Messaging {

4149

# rpc UpdateMessage(Message) returns (Message) {

4150

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4151

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

4158

# string text = 2;

4159

# }

4160

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4161

#

4162

# The following HTTP JSON to RPC mapping is enabled:

4163

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4164

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4165

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4166

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

4167

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4168

#

4169

# Note that when using `*` in the body mapping, it is not possible to

4170

# 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^]

4171

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4172

# defining REST APIs. The common usage of `*` is in custom methods

4173

# which don't use the URL at all for transferring data.

4174

#

4175

# It is possible to define multiple HTTP methods for one RPC by using

4176

# the `additional_bindings` option. Example:

4177

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4178

# service Messaging {

4179

# rpc GetMessage(GetMessageRequest) returns (Message) {

4180

# option (google.api.http) = {

4181

# get: "/v1/messages/{message_id}"

4182

# additional_bindings {

4183

# get: "/v1/users/{user_id}/messages/{message_id}"

4184

# }

4185

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4186

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4187

# }

4188

# message GetMessageRequest {

4189

# string message_id = 1;

4190

# string user_id = 2;

4191

# }

4192

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4193

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4194

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4195

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4196

# -----|-----

4197

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4198

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

4199

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4200

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4201

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4202

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4203

# 1. Leaf request fields (recursive expansion nested messages in the request

4204

# message) are classified into three categories:

4205

# - Fields referred by the path template. They are passed via the URL path.

4206

# - Fields referred by the HttpRule.body. They are passed via the HTTP

4207

# request body.

4208

# - All other fields are passed via the URL query parameters, and the

4209

# parameter name is the field path in the request message. A repeated

4210

# field can be represented as multiple query parameters under the same

4211

# name.

4212

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

4213

# are passed via URL path and HTTP request body.

4214

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

4215

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4216

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4217

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4218

#

4219

# Template = "/" Segments [ Verb ] ;

4220

# Segments = Segment { "/" Segment } ;

4221

# Segment = "*" | "**" | LITERAL | Variable ;

4222

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4223

# FieldPath = IDENT { "." IDENT } ;

4224

# Verb = ":" LITERAL ;

4225

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4226

# The syntax `*` matches a single URL path segment. The syntax `**` matches

4227

# zero or more URL path segments, which must be the last part of the URL path

4228

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4229

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4230

# The syntax `Variable` matches part of the URL path as specified by its

4231

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4232

# matches a single path segment, its template may be omitted, e.g. `{var}`

4233

# is equivalent to `{var=*}`.

4234

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4235

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

4236

# contains any reserved character, such characters should be percent-encoded

4237

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4238

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4239

# If a variable contains exactly one path segment, such as `"{var}"` or

4240

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

4241

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

4242

# server side does the reverse decoding. Such variables show up in the

4243

# [Discovery

4244

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4245

# `{var}`.

4246

#

4247

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

4248

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

4249

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

4250

# The server side does the reverse decoding, except "%2F" and "%2f" are left

4251

# unchanged. Such variables show up in the

4252

# [Discovery

4253

# Document](https://developers.google.com/discovery/v1/reference/apis) as

4254

# `{+var}`.

4255

#

4256

# ## Using gRPC API Service Configuration

4257

#

4258

# gRPC API Service Configuration (service config) is a configuration language

4259

# for configuring a gRPC service to become a user-facing product. The

4260

# service config is simply the YAML representation of the `google.api.Service`

4261

# proto message.

4262

#

4263

# As an alternative to annotating your proto file, you can configure gRPC

4264

# transcoding in your service config YAML files. You do this by specifying a

4265

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

4266

# effect as the proto annotation. This can be particularly useful if you

4267

# have a proto that is reused in multiple services. Note that any transcoding

4268

# specified in the service config will override any matching transcoding

4269

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

4276

# - selector: example.v1.Messaging.GetMessage

4277

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

4282

# proto to JSON conversion must follow the [proto3

4283

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

4284

#

4285

# While the single segment variable follows the semantics of

4286

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4287

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

4288

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

4289

# does not expand special characters like `?` and `#`, which would lead

4290

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

4291

# for multi segment variables.

4292

#

4293

# The path variables **must not** refer to any repeated or mapped field,

4294

# because client libraries are not capable of handling such variable expansion.

4295

#

4296

# The path variables **must not** capture the leading "/" character. The reason

4297

# is that the most common use case "{var}" does not capture the leading "/"

4298

# character. For consistency, all path variables must share the same behavior.

4299

#

4300

# Repeated message fields must not be mapped to URL query parameters, because

4301

# no client library can support such complicated mapping.

4302

#

4303

# If an API needs to use a JSON array for request or response body, it can map

4304

# the request or response body to a repeated field. However, some gRPC

4305

# Transcoding implementations may not support this feature.

4306

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

4307

# body, or `*` for mapping all request fields not captured by the path

4308

# 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]

4309

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4310

# NOTE: the referred field must be present at the top-level of the request

4311

# message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4312

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4313

# not contain an `additional_bindings` field themselves (that is,

4314

# the nesting may only be one level deep).

4315

# Object with schema name: HttpRule

4316

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4317

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

4318

# resources.

4319

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

4320

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

4321

# included in the `pattern` field, such as HEAD, or "*" to leave the

4322

# HTTP method unspecified for this rule. The wild-card rule is useful

4323

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4324

"path": "A String", # The path matched by this custom verb.

4325

"kind": "A String", # The name of this custom HTTP verb.

4326

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4327

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

4328

# response body. When omitted, the entire response message will be used

4329

# as the HTTP response body.

4330

#

4331

# NOTE: The referred field must be present at the top-level of the response

4332

# message type.

4333

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

4334

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

4335

"selector": "A String", # Selects a method to which this rule applies.

4336

#

4337

# Refer to selector for syntax details.

4338

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4339

},

4340

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4341

"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]

4342

# cases of single segment matches in reserved expansion, where "%2F" will be

4343

# left encoded.

4344

#

4345

# The default behavior is to not decode RFC 6570 reserved characters in multi

4346

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4347

},

4348

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4349

# of the google.protobuf.Api needs to be provided by the configuration

4350

# author, as the remaining fields will be derived from the IDL during the

4351

# normalization process. It is an error to specify an API interface here

4352

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4353

{ # Api is a light-weight descriptor for an API Interface.

4354

#

4355

# Interfaces are also described as "protocol buffer services" in some contexts,

4356

# such as by the "service" keyword in a .proto file, but they are different

4357

# from API Services, which represent a concrete implementation of an interface

4358

# as opposed to simply a description of methods and bindings. They are also

4359

# sometimes simply referred to as "APIs" in other contexts, such as the name of

4360

# this message itself. See https://cloud.google.com/apis/design/glossary for

4361

# detailed terminology.

4362

"methods": [ # The methods of this interface, in unspecified order.

4363

{ # Method represents a method of an API interface.

4364

"name": "A String", # The simple name of this method.

4365

"requestStreaming": True or False, # If true, the request is streamed.

4366

"responseTypeUrl": "A String", # The URL of the output message type.

4367

"requestTypeUrl": "A String", # A URL of the input message type.

4368

"responseStreaming": True or False, # If true, the response is streamed.

4369

"syntax": "A String", # The source syntax of this method.

4370

"options": [ # Any metadata attached to the method.

4371

{ # A protocol buffer option, which can be attached to a message, field,

4372

# enumeration, etc.

4373

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4374

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4375

# For custom options, it should be the fully-qualified name. For example,

4376

# `"google.api.http"`.

4377

"value": { # The option's value packed in an Any message. If the value is a primitive,

4378

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4379

# should be used. If the value is an enum, it should be stored as an int32

4380

# value using the google.protobuf.Int32Value type.

4381

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4387

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4388

# message.

4389

# protobuf element, like the file in which it is defined.

4390

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4391

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4392

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4393

"mixins": [ # Included interfaces. See Mixin.

4394

{ # Declares an API Interface to be included in this interface. The including

4395

# interface must redeclare all the methods from the included interface, but

4396

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4397

#

4398

# - If after comment and whitespace stripping, the documentation

4399

# string of the redeclared method is empty, it will be inherited

4400

# from the original method.

4401

#

4402

# - Each annotation belonging to the service config (http,

4403

# visibility) which is not set in the redeclared method will be

4404

# inherited.

4405

#

4406

# - If an http annotation is inherited, the path pattern will be

4407

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4408

# version of the including interface plus the root path if

4409

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4410

#

4411

# Example of a simple mixin:

4412

#

4413

# package google.acl.v1;

4414

# service AccessControl {

4415

# // Get the underlying ACL object.

4416

# rpc GetAcl(GetAclRequest) returns (Acl) {

4417

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4422

# service Storage {

4423

# // rpc GetAcl(GetAclRequest) returns (Acl);

4424

#

4425

# // Get a data record.

4426

# rpc GetData(GetDataRequest) returns (Data) {

4427

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4432

#

4433

# apis:

4434

# - name: google.storage.v2.Storage

4435

# mixins:

4436

# - name: google.acl.v1.AccessControl

4437

#

4438

# The mixin construct implies that all methods in `AccessControl` are

4439

# also declared with same name and request/response types in

4440

# `Storage`. A documentation generator or annotation processor will

4441

# see the effective `Storage.GetAcl` method after inherting

4442

# documentation and annotations as follows:

4443

#

4444

# service Storage {

4445

# // Get the underlying ACL object.

4446

# rpc GetAcl(GetAclRequest) returns (Acl) {

4447

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4453

#

4454

# If the `root` field in the mixin is specified, it should be a

4455

# relative path under which inherited HTTP paths are placed. Example:

4456

#

4457

# apis:

4458

# - name: google.storage.v2.Storage

4459

# mixins:

4460

# - name: google.acl.v1.AccessControl

4461

# root: acls

4462

#

4463

# This implies the following inherited HTTP annotation:

4464

#

4465

# service Storage {

4466

# // Get the underlying ACL object.

4467

# rpc GetAcl(GetAclRequest) returns (Acl) {

4468

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4473

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4474

"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]

4475

},

4476

],

4477

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4478

"version": "A String", # A version string for this interface. If specified, must have the form

4479

# `major-version.minor-version`, as in `1.10`. If the minor version is

4480

# omitted, it defaults to zero. If the entire version field is empty, the

4481

# major version is derived from the package name, as outlined below. If the

4482

# field is not empty, the version in the package name will be verified to be

4483

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4484

#

4485

# The versioning schema uses [semantic

4486

# versioning](http://semver.org) where the major version number

4487

# indicates a breaking change and the minor version an additive,

4488

# non-breaking change. Both version numbers are signals to users

4489

# what to expect from different versions, and should be carefully

4490

# chosen based on the product plan.

4491

#

4492

# The major version is also reflected in the package name of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4493

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4494

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4495

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4496

# experimental, non-GA interfaces.

4497

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4498

{ # A protocol buffer option, which can be attached to a message, field,

4499

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4500

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4501

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4502

# For custom options, it should be the fully-qualified name. For example,

4503

# `"google.api.http"`.

4504

"value": { # The option's value packed in an Any message. If the value is a primitive,

4505

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4506

# should be used. If the value is an enum, it should be stored as an int32

4507

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4508

"a_key": "", # Properties of the object. Contains field @type with type URL.

4509

},

4510

},

4511

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4512

"name": "A String", # The fully qualified name of this interface, including package name

4513

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4514

},

4515

],

4516

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4517

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

4525

# - google.foo.v1.AnotherError

4526

"rules": [ # The list of custom error rules that apply to individual API messages.

4527

#

4528

# **NOTE:** All service configuration rules follow "last one wins" order.

4529

{ # A custom error rule.

4530

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4531

# objects of this type will be filtered when they appear in error payload.

4532

"selector": "A String", # Selects messages to which this rule applies.

4533

#

4534

# Refer to selector for syntax details.

4535

},

4536

],

4537

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

4538

"A String",

4539

],

4540

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4541

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

4542

# usage.

4543

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4544

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4545

# - The service configuration defines a set of metrics.

4546

# - For API calls, the quota.metric_rules maps methods to metrics with

4547

# corresponding costs.

4548

# - The quota.limits defines limits on the metrics, which will be used for

4549

# quota checks at runtime.

4550

#

4551

# An example quota configuration in yaml format:

4552

#

4553

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4554

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4555

#

4556

# - name: apiWriteQpsPerProject

4557

# metric: library.googleapis.com/write_calls

4558

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

4564

# # except for the UpdateBook and DeleteBook methods. These two methods

4565

# # are mapped to the write_calls metric, with the UpdateBook method

4566

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

4571

# - selector: google.example.library.v1.LibraryService.UpdateBook

4572

# metric_costs:

4573

# library.googleapis.com/write_calls: 2

4574

# - selector: google.example.library.v1.LibraryService.DeleteBook

4575

# metric_costs:

4576

# library.googleapis.com/write_calls: 1

4577

#

4578

# Corresponding Metric definition:

4579

#

4580

# metrics:

4581

# - name: library.googleapis.com/read_calls

4582

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

4587

# display_name: Write requests

4588

# metric_kind: DELTA

4589

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4590

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4591

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

4592

# or more metrics.

4593

{ # Bind API methods to metrics. Binding a method to a metric causes that

4594

# metric's configured quota behaviors to apply to the method call.

4595

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

4596

# cost applied to each metric.

4597

#

4598

# The key of the map is the metric name, and the values are the amount

4599

# increased for the metric against which the quota limits are defined.

4600

# The value must not be negative.

4601

"a_key": "A String",

4602

},

4603

"selector": "A String", # Selects the methods to which this rule applies.

4604

#

4605

# Refer to selector for syntax details.

4606

},

4607

],

4608

"limits": [ # List of `QuotaLimit` definitions for the service.

4609

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

4610

# for a limit type. There can be at most one limit for a duration and limit

4611

# type combination defined within a `QuotaGroup`.

4612

"displayName": "A String", # User-visible display name for this limit.

4613

# Optional. If not set, the UI will provide a default display name based on

4614

# the quota configuration. This field can be used to override the default

4615

# display name generated from the configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4616

"name": "A String", # Name of the quota limit.

4617

#

4618

# The name must be provided, and it must be unique within the service. The

4619

# name can only include alphanumeric characters as well as '-'.

4620

#

4621

# The maximum length of the limit name is 64 characters.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4622

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

4623

# duration. This is the number of tokens assigned when a client

4624

# application developer activates the service for his/her project.

4625

#

4626

# Specifying a value of 0 will block all requests. This can be used if you

4627

# are provisioning quota to selected consumers and blocking others.

4628

# Similarly, a value of -1 will indicate an unlimited quota. No other

4629

# negative values are allowed.

4630

#

4631

# Used by group-based quotas only.

4632

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

4633

# the same metric will be checked together during runtime. The metric must be

4634

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4635

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

4636

# integer value that is the maximum number of requests allowed for the

4637

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4638

"a_key": "A String",

4639

},

4640

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

4641

# duration. Client application developers can override the default limit up

4642

# to this maximum. If specified, this value cannot be set to a value less

4643

# than the default limit. If not specified, it is set to the default limit.

4644

#

4645

# To allow clients to apply overrides with no upper bound, set this to -1,

4646

# indicating unlimited maximum quota.

4647

#

4648

# Used by group-based quotas only.

4649

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

4650

# For duration longer than a day, only multiple of days is supported. We

4651

# support only "100s" and "1d" for now. Additional support will be added in

4652

# the future. "0" indicates indefinite duration.

4653

#

4654

# Used by group-based quotas only.

4655

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

4656

# The free tier is the number of tokens that will be subtracted from the

4657

# billed amount when billing is enabled.

4658

# This field can only be set on a limit with duration "1d", in a billable

4659

# group; it is invalid on any other limit. If this field is not set, it

4660

# defaults to 0, indicating that there is no free tier for this service.

4661

#

4662

# Used by group-based quotas only.

4663

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

4664

# Metric.unit. The supported unit kinds are determined by the quota

4665

# backend system.

4666

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4667

# Here are some examples:

4668

# * "1/min/{project}" for quota per minute per project.

4669

#

4670

# Note: the order of unit components is insignificant.

4671

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4672

"description": "A String", # Optional. User-visible, extended description for this quota limit.

4673

# Should be used only when more context is needed to understand this limit

4674

# than provided by the limit's display name (see: `display_name`).

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]

4679

{ # Defines a metric type and its schema. Once a metric descriptor is created,

4680

# deleting or altering it stops data collection and makes the metric type's

4681

# existing data unusable.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4682

"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]

4683

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4684

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4685

# This field is optional but it is recommended to be set for any metrics

4686

# associated with user-visible concepts, such as Quota.

4687

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4688

"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]

4689

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4690

"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]

4691

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4692

"labels": [ # The set of labels that can be used to describe a specific

4693

# instance of this metric type. For example, the

4694

# `appengine.googleapis.com/http/server/response_latencies` metric

4695

# type has a label for the HTTP response code, `response_code`, so

4696

# you can look at latencies for successful responses or just

4697

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4698

{ # A description of a label.

4699

"valueType": "A String", # The type of data that can be assigned to the label.

4700

"description": "A String", # A human-readable description for the label.

4701

"key": "A String", # The label key.

4702

},

4703

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4704

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4705

"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^]

4706

# URL-encoded. All user-defined metric types have the DNS name

4707

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

4708

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4709

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4710

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4711

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4712

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4713

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

4714

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

4715

# supported units are a subset of [The Unified Code for Units of

4716

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4717

#

4718

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

4733

# * `P` peta (10**15)

4734

# * `E` exa (10**18)

4735

# * `Z` zetta (10**21)

4736

# * `Y` yotta (10**24)

4737

# * `m` milli (10**-3)

4738

# * `u` micro (10**-6)

4739

# * `n` nano (10**-9)

4740

# * `p` pico (10**-12)

4741

# * `f` femto (10**-15)

4742

# * `a` atto (10**-18)

4743

# * `z` zepto (10**-21)

4744

# * `y` yocto (10**-24)

4745

# * `Ki` kibi (2**10)

4746

# * `Mi` mebi (2**20)

4747

# * `Gi` gibi (2**30)

4748

# * `Ti` tebi (2**40)

4749

#

4750

# **Grammar**

4751

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4752

# The grammar also includes these connectors:

4753

#

4754

# * `/` division (as an infix operator, e.g. `1/s`).

4755

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

4756

#

4757

# The grammar for a unit is as follows:

4758

#

4759

# Expression = Component { "." Component } { "/" Component } ;

4760

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4761

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

4771

# equivalent to `1` if it is used alone. For examples,

4772

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

4773

# * `NAME` is a sequence of non-blank printable ASCII characters not

4774

# containing '{' or '}'.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

4775

# * `1` represents dimensionless value 1, such as in `1/s`.

4776

# * `%` represents dimensionless value 1/100, and annotates values giving

4777

# a percentage.

4778

"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.

4779

"launchStage": "A String", # Deprecated. Please use the MetricDescriptor.launch_stage instead.

4780

# The launch stage of the metric definition.

4781

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

4782

# age are guaranteed to be ingested and available to be read, excluding

4783

# data loss due to errors.

4784

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

4785

# periodically, consecutive data points are stored at this time interval,

4786

# excluding data loss due to errors. Metrics with a higher granularity have

4787

# a smaller sampling period.

4788

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4789

},

4790

],

4791

"enums": [ # A list of all enum types included in this API service. Enums

4792

# referenced directly or indirectly by the `apis` are automatically

4793

# included. Enums which are not referenced but shall be included

4794

# should be listed here by name. Example:

4795

#

4796

# enums:

4797

# - name: google.someapi.v1.SomeEnum

4798

{ # Enum type definition.

4799

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4800

# protobuf element, like the file in which it is defined.

4801

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4802

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4803

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4804

"enumvalue": [ # Enum value definitions.

4805

{ # Enum value definition.

4806

"options": [ # Protocol buffer options.

4807

{ # A protocol buffer option, which can be attached to a message, field,

4808

# enumeration, etc.

4809

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4810

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4811

# For custom options, it should be the fully-qualified name. For example,

4812

# `"google.api.http"`.

4813

"value": { # The option's value packed in an Any message. If the value is a primitive,

4814

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4815

# should be used. If the value is an enum, it should be stored as an int32

4816

# value using the google.protobuf.Int32Value type.

4817

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

4822

"number": 42, # Enum value number.

4823

},

4824

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4825

"options": [ # Protocol buffer options.

4826

{ # A protocol buffer option, which can be attached to a message, field,

4827

# enumeration, etc.

4828

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4829

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4830

# For custom options, it should be the fully-qualified name. For example,

4831

# `"google.api.http"`.

4832

"value": { # The option's value packed in an Any message. If the value is a primitive,

4833

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4834

# should be used. If the value is an enum, it should be stored as an int32

4835

# value using the google.protobuf.Int32Value type.

4836

"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]

4841

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4842

},

4843

],

4844

"types": [ # A list of all proto message types included in this API service.

4845

# Types referenced directly or indirectly by the `apis` are

4846

# automatically included. Messages which are not referenced but

4847

# shall be included, such as types used by the `google.protobuf.Any` type,

4848

# should be listed here by name. Example:

4849

#

4850

# types:

4851

# - name: google.protobuf.Int32

4852

{ # A protocol buffer message type.

4853

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4854

"A String",

4855

],

4856

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4857

"fields": [ # The list of fields.

4858

{ # A single field of a message type.

4859

"kind": "A String", # The field type.

4860

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4861

# types. The first type has index 1; zero means the type is not in the list.

4862

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4863

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4864

"name": "A String", # The field name.

4865

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4866

"jsonName": "A String", # The field JSON name.

4867

"number": 42, # The field number.

4868

"cardinality": "A String", # The field cardinality.

4869

"options": [ # The protocol buffer options.

4870

{ # A protocol buffer option, which can be attached to a message, field,

4871

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4872

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4873

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4874

# For custom options, it should be the fully-qualified name. For example,

4875

# `"google.api.http"`.

4876

"value": { # The option's value packed in an Any message. If the value is a primitive,

4877

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4878

# should be used. If the value is an enum, it should be stored as an int32

4879

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4880

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4885

},

4886

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4887

"syntax": "A String", # The source syntax.

4888

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4889

# protobuf element, like the file in which it is defined.

4890

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4891

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4892

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4893

"options": [ # The protocol buffer options.

4894

{ # A protocol buffer option, which can be attached to a message, field,

4895

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4896

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4897

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4898

# For custom options, it should be the fully-qualified name. For example,

4899

# `"google.api.http"`.

4900

"value": { # The option's value packed in an Any message. If the value is a primitive,

4901

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4902

# should be used. If the value is an enum, it should be stored as an int32

4903

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4904

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4910

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4911

#

4912

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4913

# producer and consumer projects. In the example, the `activity_history`

4914

# log is sent to both the producer and consumer projects, whereas the

4915

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4916

#

4917

# monitored_resources:

4918

# - type: library.googleapis.com/branch

4919

# labels:

4920

# - key: /city

4921

# description: The city where the library branch is located in.

4922

# - key: /name

4923

# description: The name of the branch.

4924

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4925

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4926

# labels:

4927

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4928

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4929

# logging:

4930

# producer_destinations:

4931

# - monitored_resource: library.googleapis.com/branch

4932

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4933

# - activity_history

4934

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4935

# consumer_destinations:

4936

# - monitored_resource: library.googleapis.com/branch

4937

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4938

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4939

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4940

# There can be multiple producer destinations, each one must have a

4941

# different monitored resource type. A log can be used in at most

4942

# one producer destination.

4943

{ # Configuration of a specific logging destination (the producer project

4944

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4945

"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]

4946

# Service.monitored_resources section.

4947

"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]

4948

# be defined in the Service.logs section. If the log name is

4949

# not a domain scoped name, it will be automatically prefixed with

4950

# 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.

4956

# There can be multiple consumer destinations, each one must have a

4957

# different monitored resource type. A log can be used in at most

4958

# one consumer destination.

4959

{ # Configuration of a specific logging destination (the producer project

4960

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4961

"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]

4962

# Service.monitored_resources section.

4963

"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]

4964

# be defined in the Service.logs section. If the log name is

4965

# not a domain scoped name, it will be automatically prefixed with

4966

# 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^]

4972

"name": "A String", # The service name, which is a DNS-like logical identifier for the

4973

# service, such as `calendar.googleapis.com`. The service name

4974

# typically goes through DNS verification to make sure the owner

4975

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4976

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4977

#

4978

# Example:

4979

# <pre><code>documentation:

4980

# summary: >

4981

# The Google Calendar API gives access

4982

# to most calendar features.

4983

# pages:

4984

# - name: Overview

4985

# content: (== include google/foo/overview.md ==)

4986

# - name: Tutorial

4987

# content: (== include google/foo/tutorial.md ==)

4988

# subpages;

4989

# - name: Java

4990

# content: (== include google/foo/tutorial_java.md ==)

4991

# rules:

4992

# - selector: google.calendar.Calendar.Get

4993

# description: >

4994

# ...

4995

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5000

# standard markdown features, definition lists, tables and fenced

5001

# code blocks are supported. Section headers can be provided and are

5002

# interpreted relative to the section nesting of the context where

5003

# a documentation fragment is embedded.

5004

#

5005

# Documentation from the IDL is merged with documentation defined

5006

# via the config at normalization time, where documentation provided

5007

# by config rules overrides IDL provided.

5008

#

5009

# A number of constructs specific to the API platform are supported

5010

# in documentation text.

5011

#

5012

# In order to reference a proto element, the following

5013

# notation can be used:

5014

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5015

# To override the display text used for the link, this can be used:

5016

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5017

# Text can be excluded from doc using the following notation:

5018

# <pre><code>(-- internal comment --)</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5019

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5020

# A few directives are available in documentation. Note that

5021

# directives must appear on a single line to be properly

5022

# identified. The `include` directive includes a markdown file from

5023

# an external source:

5024

# <pre><code>(== include path/to/file ==)</code></pre>

5025

# The `resource_for` directive marks a message to be the resource of

5026

# a collection in REST view. If it is not specified, tools attempt

5027

# to infer the resource from the operations in a collection:

5028

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5029

# The directive `suppress_warning` does not directly affect documentation

5030

# and is documented together with service config validation.

5031

"rules": [ # A list of documentation rules that apply to individual API elements.

5032

#

5033

# **NOTE:** All service configuration rules follow "last one wins" order.

5034

{ # A documentation rule provides information about individual API elements.

5035

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5036

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

5037

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5038

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5039

# qualified name of the element which may end in "*", indicating a wildcard.

5040

# 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^]

5041

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

5042

# wildcard will match one or more components. To specify a default for all

5043

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5044

},

5045

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5046

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5047

"overview": "A String", # Declares a single overview page. For example:

5048

# <pre><code>documentation:

5049

# summary: ...

5050

# overview: (== include overview.md ==)

5051

# </code></pre>

5052

# This is a shortcut for the following declaration (using pages style):

5053

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5058

# </code></pre>

5059

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5060

"pages": [ # The top level pages for the documentation set.

5061

{ # Represents a documentation page. A page can contain subpages to represent

5062

# nested documentation set structure.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5063

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path}

5064

# ==)</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5065

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5066

# honored in the generated docset.

5067

# Object with schema name: Page

5068

],

5069

"name": "A String", # The name of the page. It will be used as an identity of the page to

5070

# generate URI of the page, text of the link to this page in navigation,

5071

# etc. The full page name (start from the root page name to this page

5072

# concatenated with `.`) can be used as reference to the page in your

5073

# documentation. For example:

5074

# <pre><code>pages:

5075

# - name: Tutorial

5076

# content: (== include tutorial.md ==)

5077

# subpages:

5078

# - name: Java

5079

# content: (== include tutorial_java.md ==)

5080

# </code></pre>

5081

# You can reference `Java` page using Markdown reference link syntax:

5082

# `Java`.

5083

},

5084

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5085

"summary": "A String", # A short summary of what the service does. Can only be provided by

5086

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5087

},

5088

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

5089

"sourceFiles": [ # All files used during config generation.

5090

{

5091

"a_key": "", # Properties of the object. Contains field @type with type URL.

5092

},

5093

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5094

},

5095

"systemTypes": [ # A list of all proto message types included in this API service.

5096

# It serves similar purpose as [google.api.Service.types], except that

5097

# these types are not needed by user-defined APIs. Therefore, they will not

5098

# show up in the generated discovery doc. This field should only be used

5099

# to define system APIs in ESF.

5100

{ # A protocol buffer message type.

5101

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5102

"A String",

5103

],

5104

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5105

"fields": [ # The list of fields.

5106

{ # A single field of a message type.

5107

"kind": "A String", # The field type.

5108

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5109

# types. The first type has index 1; zero means the type is not in the list.

5110

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5111

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5112

"name": "A String", # The field name.

5113

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5114

"jsonName": "A String", # The field JSON name.

5115

"number": 42, # The field number.

5116

"cardinality": "A String", # The field cardinality.

5117

"options": [ # The protocol buffer options.

5118

{ # A protocol buffer option, which can be attached to a message, field,

5119

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5120

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5121

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5122

# For custom options, it should be the fully-qualified name. For example,

5123

# `"google.api.http"`.

5124

"value": { # The option's value packed in an Any message. If the value is a primitive,

5125

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5126

# should be used. If the value is an enum, it should be stored as an int32

5127

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5128

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5133

},

5134

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5135

"syntax": "A String", # The source syntax.

5136

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5137

# protobuf element, like the file in which it is defined.

5138

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5139

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5140

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5141

"options": [ # The protocol buffer options.

5142

{ # A protocol buffer option, which can be attached to a message, field,

5143

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5144

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5145

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5146

# For custom options, it should be the fully-qualified name. For example,

5147

# `"google.api.http"`.

5148

"value": { # The option's value packed in an Any message. If the value is a primitive,

5149

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5150

# should be used. If the value is an enum, it should be stored as an int32

5151

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5152

"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

5167

# - google.rpc.context.OriginContext

5168

#

5169

# The above specifies that all methods in the API request

5170

# `google.rpc.context.ProjectContext` and

5171

# `google.rpc.context.OriginContext`.

5172

#

5173

# Available context types are defined in package

5174

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5175

#

5176

# This also provides mechanism to whitelist any protobuf message extension that

5177

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

5178

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

5179

# 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"

5187

# allowed_request_extensions:

5188

# - google.foo.v1.NewExtension

5189

# allowed_response_extensions:

5190

# - google.foo.v1.NewExtension

5191

#

5192

# You can also specify extension ID instead of fully qualified extension name

5193

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5194

"rules": [ # A list of RPC context rules that apply to individual API methods.

5195

#

5196

# **NOTE:** All service configuration rules follow "last one wins" order.

5197

{ # A context rule provides information about the context for an individual API

5198

# element.

5199

"provided": [ # A list of full type names of provided contexts.

5200

"A String",

5201

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5202

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5203

# side channel from backend to client.

5204

"A String",

5205

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5206

"selector": "A String", # Selects the methods to which this rule applies.

5207

#

5208

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5209

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

5210

# side channel from client to backend.

5211

"A String",

5212

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5213

"requested": [ # A list of full type names of requested contexts.

5214

"A String",

5215

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5216

},

5217

],

5218

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5219

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5220

# with the same name as the service is automatically generated to service all

5221

# defined APIs.

5222

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5223

# A service may expose any number of endpoints, and all endpoints share the

5224

# same service configuration, such as quota configuration and monitoring

5225

# configuration.

5226

#

5227

# Example service configuration:

5228

#

5229

# name: library-example.googleapis.com

5230

# endpoints:

5231

# # Below entry makes 'google.example.library.v1.Library'

5232

# # API be served from endpoint address library-example.googleapis.com.

5233

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5234

# # it to decide whether the subsequent cross-origin request is

5235

# # allowed to proceed.

5236

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5237

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5238

"allowCors": True or False, # Allowing

5239

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5240

# cross-domain traffic, would allow the backends served from this endpoint to

5241

# receive and respond to HTTP OPTIONS requests. The response will be used by

5242

# the browser to determine whether the subsequent cross-origin request is

5243

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5244

"target": "A String", # The specification of an Internet routable address of API frontend that will

5245

# handle requests to this [API

5246

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

5247

# either a valid IPv4 address or a fully-qualified domain name. For example,

5248

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5249

"features": [ # The list of features enabled on this endpoint.

5250

"A String",

5251

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5252

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5253

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5254

# please specify multiple google.api.Endpoint for each of the intended

5255

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5256

#

5257

# 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]

5266

<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]

5267

<pre>Lists the history of the service configuration for a managed service,

5268

from the newest to the oldest.

5269

5270

Args:

5271

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5272

for naming requirements. For example: `example.googleapis.com`. (required)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5273

pageSize: integer, The max number of items to include in the response list. Page size is 50

5274

if not specified. Maximum value is 100.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5275

pageToken: string, The token of the page to retrieve.

5276

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5283

5284

{ # Response message for ListServiceConfigs method.

5285

"nextPageToken": "A String", # The token of the next page of results.

5286

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5287

{ # `Service` is the root object of Google service configuration schema. It

5288

# describes basic information about a service, such as the name and the

5289

# title, and delegates other aspects to sub-sections. Each sub-section is

5290

# either a proto message or a repeated proto message that configures a

5291

# 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]

5296

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5297

# name: calendar.googleapis.com

5298

# title: Google Calendar API

5299

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5300

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5301

# authentication:

5302

# providers:

5303

# - id: google_calendar_auth

5304

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5305

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5306

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5307

# - selector: "*"

5308

# requirements:

5309

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5310

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

5311

# service controller handles features like abuse, quota, billing, logging,

5312

# monitoring, etc.

5313

"environment": "A String", # The service control environment to use. If empty, no control plane

5314

# feature (like quota and billing) will be enabled.

5315

},

5316

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5317

# by the Service.monitoring and Service.logging configurations.

5318

{ # An object that describes the schema of a MonitoredResource object using a

5319

# type name and a set of labels. For example, the monitored resource

5320

# descriptor for Google Compute Engine VM instances has a type of

5321

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5322

# `"zone"` to identify particular VM instances.

5323

#

5324

# Different APIs can support different monitored resource types. APIs generally

5325

# provide a `list` method that returns the monitored resource descriptors used

5326

# by the API.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5327

#

5328

# Next ID: 10

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5329

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5330

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5331

# without any article or other determiners. For example,

5332

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5333

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5334

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5335

# {type} is the value of the `type` field in this object and

5336

# {project_id} is a project ID that provides API-specific context for

5337

# accessing the type. APIs that do not use project information can use the

5338

# resource name format `"monitoredResourceDescriptors/{type}"`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5339

"labels": [ # Required. A set of labels used to describe instances of this monitored

5340

# resource type. For example, an individual Google Cloud SQL database is

5341

# identified by values for the labels `"database_id"` and `"zone"`.

5342

{ # A description of a label.

5343

"valueType": "A String", # The type of data that can be assigned to the label.

5344

"description": "A String", # A human-readable description for the label.

5345

"key": "A String", # The label key.

5346

},

5347

],

5348

"launchStage": "A String", # Optional. The launch stage of the monitored resource definition.

5349

"type": "A String", # Required. The monitored resource type. For example, the type

5350

# `"cloudsql_database"` represents databases in Google Cloud SQL.

5351

# The maximum length of this value is 256 characters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5352

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5353

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5354

},

5355

],

5356

"logs": [ # Defines the logs used by this service.

5357

{ # A description of a log type. Example in YAML format:

5358

#

5359

# - name: library.googleapis.com/activity_history

5360

# description: The history of borrowing and returning library items.

5361

# display_name: Activity

5362

# labels:

5363

# - key: /customer_id

5364

# description: Identifier of a library customer

5365

"labels": [ # The set of labels that are available to describe a specific log entry.

5366

# Runtime requests that contain labels not specified here are

5367

# considered invalid.

5368

{ # A description of a label.

5369

"valueType": "A String", # The type of data that can be assigned to the label.

5370

"description": "A String", # A human-readable description for the label.

5371

"key": "A String", # The label key.

5372

},

5373

],

5374

"displayName": "A String", # The human-readable name for this log. This information appears on

5375

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5376

"name": "A String", # The name of the log. It must be less than 512 characters long and can

5377

# include the following characters: upper- and lower-case alphanumeric

5378

# characters [A-Za-z0-9], and punctuation characters including

5379

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5380

"description": "A String", # A human-readable description of this log. This information appears in

5381

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5382

},

5383

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5384

"systemParameters": { # ### System parameter configuration # System parameter configuration.

5385

#

5386

# A system parameter is a special kind of parameter defined by the API

5387

# system, not by an individual API. It is typically mapped to an HTTP header

5388

# and/or a URL query parameter. This configuration specifies which methods

5389

# change the names of the system parameters.

5390

"rules": [ # Define system parameters.

5391

#

5392

# The parameters defined here will override the default parameters

5393

# implemented by the system. If this field is missing from the service

5394

# config, default system parameters will be used. Default system parameters

5395

# and names is implementation-dependent.

5396

#

5397

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

5405

#

5406

#

5407

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

5412

# parameters:

5413

# - name: api_key

5414

# http_header: Api-Key1

5415

# - name: api_key

5416

# http_header: Api-Key2

5417

#

5418

# **NOTE:** All service configuration rules follow "last one wins" order.

5419

{ # Define a system parameter rule mapping system parameter definitions to

5420

# methods.

5421

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

5422

# For a given method call, only one of them should be used. If multiple

5423

# names are used the behavior is implementation-dependent.

5424

# If none of the specified names are present the behavior is

5425

# parameter-dependent.

5426

{ # Define a parameter's name and location. The parameter may be passed as either

5427

# an HTTP header or a URL query parameter, and if both are passed the behavior

5428

# is implementation-dependent.

5429

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

5430

# sensitive.

5431

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

5432

# insensitive.

5433

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

5434

},

5435

],

5436

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5437

# methods in all APIs.

5438

#

5439

# Refer to selector for syntax details.

5440

},

5441

],

5442

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5443

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5444

# by the client for tracking purpose. If empty, the server may choose to

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5445

# generate one instead. Must be no longer than 60 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5446

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

5447

"rules": [ # A list of API backend rules that apply to individual API methods.

5448

#

5449

# **NOTE:** All service configuration rules follow "last one wins" order.

5450

{ # A backend rule provides configuration for an individual API element.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5451

"jwtAudience": "A String", # The JWT audience is used when generating a JWT id token for the backend.

5452

"pathTranslation": "A String",

5453

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

5454

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5455

"selector": "A String", # Selects the methods to which this rule applies.

5456

#

5457

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5458

"operationDeadline": 3.14, # The number of seconds to wait for the completion of a long running

5459

# operation. The default is no deadline.

5460

"deadline": 3.14, # The number of seconds to wait for a response from a request. The default

5461

# deadline for gRPC is infinite (no deadline) and HTTP requests is 5 seconds.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5462

"address": "A String", # The address of the API backend.

5463

},

5464

],

5465

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5466

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5467

#

5468

# The example below shows how to configure monitored resources and metrics

5469

# for monitoring. In the example, a monitored resource and two metrics are

5470

# defined. The `library.googleapis.com/book/returned_count` metric is sent

5471

# to both producer and consumer projects, whereas the

5472

# `library.googleapis.com/book/overdue_count` metric is only sent to the

5473

# consumer project.

5474

#

5475

# monitored_resources:

5476

# - type: library.googleapis.com/branch

5477

# labels:

5478

# - key: /city

5479

# description: The city where the library branch is located in.

5480

# - key: /name

5481

# description: The name of the branch.

5482

# metrics:

5483

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

5488

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

5493

# monitoring:

5494

# producer_destinations:

5495

# - monitored_resource: library.googleapis.com/branch

5496

# metrics:

5497

# - library.googleapis.com/book/returned_count

5498

# consumer_destinations:

5499

# - monitored_resource: library.googleapis.com/branch

5500

# metrics:

5501

# - library.googleapis.com/book/returned_count

5502

# - library.googleapis.com/book/overdue_count

5503

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5504

# There can be multiple producer destinations. A monitored resouce type may

5505

# appear in multiple monitoring destinations if different aggregations are

5506

# needed for different sets of metrics associated with that monitored

5507

# resource type. A monitored resource and metric pair may only be used once

5508

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5509

{ # Configuration of a specific monitoring destination (the producer project

5510

# or the consumer project).

5511

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5512

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5513

"metrics": [ # Types of the metrics to report to this monitoring destination.

5514

# 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^]

5520

# There can be multiple consumer destinations. A monitored resouce type may

5521

# appear in multiple monitoring destinations if different aggregations are

5522

# needed for different sets of metrics associated with that monitored

5523

# resource type. A monitored resource and metric pair may only be used once

5524

# in the Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5525

{ # Configuration of a specific monitoring destination (the producer project

5526

# or the consumer project).

5527

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5528

# Service.monitored_resources section.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5529

"metrics": [ # Types of the metrics to report to this monitoring destination.

5530

# Each type must be defined in Service.metrics section.

"A String",

],

},

],

},

"billing": { # Billing related configuration of the service. # Billing configuration.

5537

#

5538

# The following example shows how to configure monitored resources and metrics

5539

# for billing:

5540

#

5541

# monitored_resources:

5542

# - type: library.googleapis.com/branch

5543

# labels:

5544

# - key: /city

5545

# description: The city where the library branch is located in.

5546

# - key: /name

5547

# description: The name of the branch.

5548

# metrics:

5549

# - name: library.googleapis.com/book/borrowed_count

# metric_kind: DELTA

# value_type: INT64

# billing:

# consumer_destinations:

5554

# - monitored_resource: library.googleapis.com/branch

5555

# metrics:

5556

# - library.googleapis.com/book/borrowed_count

5557

"consumerDestinations": [ # Billing configurations for sending metrics to the consumer project.

5558

# There can be multiple consumer destinations per service, each one must have

5559

# a different monitored resource type. A metric can be used in at most

5560

# one consumer destination.

5561

{ # Configuration of a specific billing destination (Currently only support

5562

# bill against consumer project).

5563

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5564

# Service.monitored_resources section.

5565

"metrics": [ # Names of the metrics to report to this billing destination.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5566

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5572

"title": "A String", # The product title for this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5573

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

5574

#

5575

# Example for an API targeted for external use:

5576

#

5577

# name: calendar.googleapis.com

5578

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5579

# providers:

5580

# - id: google_calendar_auth

5581

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5582

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5583

# rules:

5584

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5585

# requirements:

5586

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5587

"rules": [ # A list of authentication rules that apply to individual API methods.

5588

#

5589

# **NOTE:** All service configuration rules follow "last one wins" order.

5590

{ # Authentication rules for the service.

5591

#

5592

# By default, if a method has any authentication requirements, every request

5593

# must include a valid credential matching one of the requirements.

5594

# It's an error to include more than one kind of credential in a single

5595

# request.

5596

#

5597

# If a method doesn't have any auth requirements, request credentials will be

5598

# ignored.

5599

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

5600

# there are scopes defined for "Read-only access to Google Calendar" and

5601

# "Access to Cloud Platform". Users can consent to a scope for an application,

5602

# giving it permission to access that data on their behalf.

5603

#

5604

# OAuth scope specifications should be fairly coarse grained; a user will need

5605

# to see and understand the text description of what your scope means.

5606

#

5607

# In most cases: use one or at most two OAuth scopes for an entire family of

5608

# products. If your product has multiple APIs, you should probably be sharing

5609

# the OAuth scope across all of those APIs.

5610

#

5611

# When you need finer grained OAuth consent screens: talk with your product

5612

# management about how developers will use them in practice.

5613

#

5614

# Please note that even though each of the canonical scopes is enough for a

5615

# request to be accepted and passed to the backend, a request can still fail

5616

# due to the backend requiring additional scopes or permissions.

5617

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

5618

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

5623

# https://www.googleapis.com/auth/calendar.read

5624

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5625

"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]

5626

"requirements": [ # Requirements for additional authentication providers.

5627

{ # User-defined authentication requirements, including support for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5628

# [JSON Web Token

5629

# (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]

5630

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5635

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

5636

# implemented and accepted in all the runtime components.

5637

#

5638

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5639

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5640

# that are allowed to access. A JWT containing any of these audiences will

5641

# be accepted. When this setting is absent, only JWTs with audience

5642

# "https://Service_name/API_name"

5643

# will be accepted. For example, if no audiences are in the setting,

5644

# LibraryService API will only accept JWTs with the following audience

5645

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5650

# bookstore_web.apps.googleusercontent.com

5651

},

5652

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5653

"selector": "A String", # Selects the methods to which this rule applies.

5654

#

5655

# Refer to selector for syntax details.

5656

},

5657

],

5658

"providers": [ # Defines a set of authentication providers that a service supports.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5659

{ # Configuration for an authentication provider, including support for

5660

# [JSON Web Token

5661

# (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5662

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

5663

# [OpenID

5664

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

5665

# Optional if the key set document:

5666

# - can be retrieved from

5667

# [OpenID

5668

# Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html of

5669

# the issuer.

5670

# - can be inferred from the email domain of the issuer (e.g. a Google

5671

# service account).

5672

#

5673

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5674

"audiences": "A String", # The list of JWT

5675

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5676

# that are allowed to access. A JWT containing any of these audiences will

5677

# be accepted. When this setting is absent, only JWTs with audience

5678

# "https://Service_name/API_name"

5679

# will be accepted. For example, if no audiences are in the setting,

5680

# LibraryService API will only accept JWTs with the following audience

5681

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5686

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5687

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

5688

# `AuthRequirement.provider_id`.

5689

#

5690

# Example: "bookstore_auth".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5691

"authorizationUrl": "A String", # Redirect URL if JWT token is required but not present or is expired.

5692

# Implement authorizationUrl of securityDefinitions in OpenAPI spec.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5693

"issuer": "A String", # Identifies the principal that issued the JWT. See

5694

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

5695

# Usually a URL or an email address.

5696

#

5697

# Example: https://securetoken.google.com

5698

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

5703

"rules": [ # A list of usage rules that apply to individual API methods.

5704

#

5705

# **NOTE:** All service configuration rules follow "last one wins" order.

5706

{ # Usage configuration rules for the service.

5707

#

5708

# NOTE: Under development.

5709

#

5710

#

5711

# Use this rule to configure unregistered calls for the service. Unregistered

5712

# calls are calls that do not contain consumer project identity.

5713

# (Example: calls that do not contain an API key).

5714

# By default, API methods do not allow unregistered calls, and each method call

5715

# must be identified by a consumer project identity. Use this rule to

5716

# allow/disallow unregistered calls.

5717

#

5718

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

5724

#

5725

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

5730

# allow_unregistered_calls: true

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5731

"skipServiceControl": True or False, # If true, the selected method should skip service control and the control

5732

# plane features, such as quota and billing, will not be available.

5733

# This flag is used by Google Cloud Endpoints to bypass checks for internal

5734

# methods, such as service health check methods.

5735

"allowUnregisteredCalls": True or False, # If true, the selected method allows unregistered calls, e.g. calls

5736

# that don't identify any user or application.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5737

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5738

# methods in all APIs.

5739

#

5740

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5741

},

5742

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5743

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

5744

# service producer.

5745

#

5746

# Google Service Management currently only supports

5747

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

5748

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

5749

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

5750

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5751

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

5752

# service. Each requirement is of the form <service.name>/<requirement-id>;

5753

# for example 'serviceusage.googleapis.com/billing-enabled'.

5754

"A String",

5755

],

5756

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5757

"configVersion": 42, # The semantic version of the service configuration. The config version

5758

# affects the interpretation of the service configuration. For example,

5759

# certain features are enabled by default for certain config versions.

5760

# The latest config version is `3`.

5761

"producerProjectId": "A String", # The Google project that owns this service.

5762

"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]

5763

# HttpRule, each specifying the mapping of an RPC method

5764

# to one or more HTTP REST API methods.

5765

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

5766

#

5767

# **NOTE:** All service configuration rules follow "last one wins" order.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5768

{ # # gRPC Transcoding

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5769

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5770

# gRPC Transcoding is a feature for mapping between a gRPC method and one or

5771

# more HTTP REST endpoints. It allows developers to build a single API service

5772

# that supports both gRPC APIs and REST APIs. Many systems, including [Google

5773

# APIs](https://github.com/googleapis/googleapis),

5774

# [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC

5775

# Gateway](https://github.com/grpc-ecosystem/grpc-gateway),

5776

# and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature

5777

# and use it for large scale production services.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5778

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5779

# `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies

5780

# how different portions of the gRPC request message are mapped to the URL

5781

# path, URL query parameters, and HTTP request body. It also controls how the

5782

# gRPC response message is mapped to the HTTP response body. `HttpRule` is

5783

# typically specified as an `google.api.http` annotation on the gRPC method.

5784

#

5785

# Each mapping specifies a URL path template and an HTTP method. The path

5786

# template may refer to one or more fields in the gRPC request message, as long

5787

# as each field is a non-repeated field with a primitive (non-message) type.

5788

# The path template controls how fields of the request message are mapped to

5789

# the URL path.

5790

#

5791

# Example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5792

#

5793

# service Messaging {

5794

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5795

# option (google.api.http) = {

5796

# get: "/v1/{name=messages/*}"

5797

# };

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5798

# }

5799

# }

5800

# message GetMessageRequest {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5801

# string name = 1; // Mapped to URL path.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5802

# }

5803

# message Message {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5804

# string text = 1; // The resource content.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5805

# }

5806

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5807

# This enables an HTTP REST to gRPC mapping as below:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5808

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5809

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5810

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5811

# `GET /v1/messages/123456` | `GetMessage(name: "messages/123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5812

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5813

# Any fields in the request message which are not bound by the path template

5814

# automatically become HTTP query parameters if there is no HTTP request body.

5815

# For example:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5816

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5817

# service Messaging {

5818

# rpc GetMessage(GetMessageRequest) returns (Message) {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5819

# option (google.api.http) = {

5820

# get:"/v1/messages/{message_id}"

5821

# };

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5822

# }

5823

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5824

# message GetMessageRequest {

5825

# message SubMessage {

5826

# string subfield = 1;

5827

# }

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5828

# string message_id = 1; // Mapped to URL path.

5829

# int64 revision = 2; // Mapped to URL query parameter `revision`.

5830

# SubMessage sub = 3; // Mapped to URL query parameter `sub.subfield`.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5831

# }

5832

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5833

# This enables a HTTP JSON to RPC mapping as below:

5834

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5835

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5836

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5837

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` |

5838

# `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield:

5839

# "foo"))`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5840

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5841

# Note that fields which are mapped to URL query parameters must have a

5842

# primitive type or a repeated primitive type or a non-repeated message type.

5843

# In the case of a repeated type, the parameter can be repeated in the URL

5844

# as `...?param=A&param=B`. In the case of a message type, each field of the

5845

# message is mapped to a separate parameter, such as

5846

# `...?foo.a=A&foo.b=B&foo.c=C`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5847

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5848

# For HTTP methods that allow a request body, the `body` field

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5849

# specifies the mapping. Consider a REST update method on the

5850

# message resource collection:

5851

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5852

# service Messaging {

5853

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

5854

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5855

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

5861

# string message_id = 1; // mapped to the URL

5862

# Message message = 2; // mapped to the body

5863

# }

5864

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5865

# The following HTTP JSON to RPC mapping is enabled, where the

5866

# representation of the JSON in the request body is determined by

5867

# protos JSON encoding:

5868

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5869

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5870

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5871

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

5872

# "123456" message { text: "Hi!" })`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5873

#

5874

# The special name `*` can be used in the body mapping to define that

5875

# every field not bound by the path template should be mapped to the

5876

# request body. This enables the following alternative definition of

5877

# the update method:

5878

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5879

# service Messaging {

5880

# rpc UpdateMessage(Message) returns (Message) {

5881

# option (google.api.http) = {

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5882

# patch: "/v1/messages/{message_id}"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

5889

# string text = 2;

5890

# }

5891

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5892

#

5893

# The following HTTP JSON to RPC mapping is enabled:

5894

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5895

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5896

# -----|-----

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5897

# `PATCH /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id:

5898

# "123456" text: "Hi!")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5899

#

5900

# Note that when using `*` in the body mapping, it is not possible to

5901

# 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^]

5902

# the body. This makes this option more rarely used in practice when

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5903

# defining REST APIs. The common usage of `*` is in custom methods

5904

# which don't use the URL at all for transferring data.

5905

#

5906

# It is possible to define multiple HTTP methods for one RPC by using

5907

# the `additional_bindings` option. Example:

5908

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5909

# service Messaging {

5910

# rpc GetMessage(GetMessageRequest) returns (Message) {

5911

# option (google.api.http) = {

5912

# get: "/v1/messages/{message_id}"

5913

# additional_bindings {

5914

# get: "/v1/users/{user_id}/messages/{message_id}"

5915

# }

5916

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5917

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5918

# }

5919

# message GetMessageRequest {

5920

# string message_id = 1;

5921

# string user_id = 2;

5922

# }

5923

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5924

# This enables the following two alternative HTTP JSON to RPC mappings:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5925

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5926

# HTTP | gRPC

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5927

# -----|-----

5928

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5929

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id:

5930

# "123456")`

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5931

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5932

# ## Rules for HTTP mapping

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5933

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5934

# 1. Leaf request fields (recursive expansion nested messages in the request

5935

# message) are classified into three categories:

5936

# - Fields referred by the path template. They are passed via the URL path.

5937

# - Fields referred by the HttpRule.body. They are passed via the HTTP

5938

# request body.

5939

# - All other fields are passed via the URL query parameters, and the

5940

# parameter name is the field path in the request message. A repeated

5941

# field can be represented as multiple query parameters under the same

5942

# name.

5943

# 2. If HttpRule.body is "*", there is no URL query parameter, all fields

5944

# are passed via URL path and HTTP request body.

5945

# 3. If HttpRule.body is omitted, there is no HTTP request body, all

5946

# fields are passed via URL path and URL query parameters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5947

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5948

# ### Path template syntax

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5949

#

5950

# Template = "/" Segments [ Verb ] ;

5951

# Segments = Segment { "/" Segment } ;

5952

# Segment = "*" | "**" | LITERAL | Variable ;

5953

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5954

# FieldPath = IDENT { "." IDENT } ;

5955

# Verb = ":" LITERAL ;

5956

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5957

# The syntax `*` matches a single URL path segment. The syntax `**` matches

5958

# zero or more URL path segments, which must be the last part of the URL path

5959

# except the `Verb`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5960

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5961

# The syntax `Variable` matches part of the URL path as specified by its

5962

# template. A variable template must not contain other variables. If a variable

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5963

# matches a single path segment, its template may be omitted, e.g. `{var}`

5964

# is equivalent to `{var=*}`.

5965

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5966

# The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`

5967

# contains any reserved character, such characters should be percent-encoded

5968

# before the matching.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5969

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

5970

# If a variable contains exactly one path segment, such as `"{var}"` or

5971

# `"{var=*}"`, when such a variable is expanded into a URL path on the client

5972

# side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The

5973

# server side does the reverse decoding. Such variables show up in the

5974

# [Discovery

5975

# Document](https://developers.google.com/discovery/v1/reference/apis) as

5976

# `{var}`.

5977

#

5978

# If a variable contains multiple path segments, such as `"{var=foo/*}"`

5979

# or `"{var=**}"`, when such a variable is expanded into a URL path on the

5980

# client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.

5981

# The server side does the reverse decoding, except "%2F" and "%2f" are left

5982

# unchanged. Such variables show up in the

5983

# [Discovery

5984

# Document](https://developers.google.com/discovery/v1/reference/apis) as

5985

# `{+var}`.

5986

#

5987

# ## Using gRPC API Service Configuration

5988

#

5989

# gRPC API Service Configuration (service config) is a configuration language

5990

# for configuring a gRPC service to become a user-facing product. The

5991

# service config is simply the YAML representation of the `google.api.Service`

5992

# proto message.

5993

#

5994

# As an alternative to annotating your proto file, you can configure gRPC

5995

# transcoding in your service config YAML files. You do this by specifying a

5996

# `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same

5997

# effect as the proto annotation. This can be particularly useful if you

5998

# have a proto that is reused in multiple services. Note that any transcoding

5999

# specified in the service config will override any matching transcoding

6000

# configuration in the proto.

#

# Example:

#

# http:

# rules:

# # Selects a gRPC method and applies HttpRule to it.

6007

# - selector: example.v1.Messaging.GetMessage

6008

# get: /v1/messages/{message_id}/{sub.subfield}

#

# ## Special notes

#

# When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the

6013

# proto to JSON conversion must follow the [proto3

6014

# specification](https://developers.google.com/protocol-buffers/docs/proto3#json).

6015

#

6016

# While the single segment variable follows the semantics of

6017

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

6018

# Expansion, the multi segment variable **does not** follow RFC 6570 Section

6019

# 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion

6020

# does not expand special characters like `?` and `#`, which would lead

6021

# to invalid URLs. As the result, gRPC Transcoding uses a custom encoding

6022

# for multi segment variables.

6023

#

6024

# The path variables **must not** refer to any repeated or mapped field,

6025

# because client libraries are not capable of handling such variable expansion.

6026

#

6027

# The path variables **must not** capture the leading "/" character. The reason

6028

# is that the most common use case "{var}" does not capture the leading "/"

6029

# character. For consistency, all path variables must share the same behavior.

6030

#

6031

# Repeated message fields must not be mapped to URL query parameters, because

6032

# no client library can support such complicated mapping.

6033

#

6034

# If an API needs to use a JSON array for request or response body, it can map

6035

# the request or response body to a repeated field. However, some gRPC

6036

# Transcoding implementations may not support this feature.

6037

"body": "A String", # The name of the request field whose value is mapped to the HTTP request

6038

# body, or `*` for mapping all request fields not captured by the path

6039

# 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]

6040

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6041

# NOTE: the referred field must be present at the top-level of the request

6042

# message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6043

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

6044

# not contain an `additional_bindings` field themselves (that is,

6045

# the nesting may only be one level deep).

6046

# Object with schema name: HttpRule

6047

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6048

"get": "A String", # Maps to HTTP GET. Used for listing and getting information about

6049

# resources.

6050

"patch": "A String", # Maps to HTTP PATCH. Used for updating a resource.

6051

"custom": { # A custom pattern is used for defining custom HTTP verb. # The custom pattern is used for specifying an HTTP method that is not

6052

# included in the `pattern` field, such as HEAD, or "*" to leave the

6053

# HTTP method unspecified for this rule. The wild-card rule is useful

6054

# for services that provide content to Web (HTML) clients.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6055

"path": "A String", # The path matched by this custom verb.

6056

"kind": "A String", # The name of this custom HTTP verb.

6057

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6058

"responseBody": "A String", # Optional. The name of the response field whose value is mapped to the HTTP

6059

# response body. When omitted, the entire response message will be used

6060

# as the HTTP response body.

6061

#

6062

# NOTE: The referred field must be present at the top-level of the response

6063

# message type.

6064

"put": "A String", # Maps to HTTP PUT. Used for replacing a resource.

6065

"post": "A String", # Maps to HTTP POST. Used for creating a resource or performing an action.

6066

"selector": "A String", # Selects a method to which this rule applies.

6067

#

6068

# Refer to selector for syntax details.

6069

"delete": "A String", # Maps to HTTP DELETE. Used for deleting a resource.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6070

},

6071

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6072

"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]

6073

# cases of single segment matches in reserved expansion, where "%2F" will be

6074

# left encoded.

6075

#

6076

# The default behavior is to not decode RFC 6570 reserved characters in multi

6077

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6078

},

6079

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

6080

# of the google.protobuf.Api needs to be provided by the configuration

6081

# author, as the remaining fields will be derived from the IDL during the

6082

# normalization process. It is an error to specify an API interface here

6083

# which cannot be resolved against the associated IDL files.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6084

{ # Api is a light-weight descriptor for an API Interface.

6085

#

6086

# Interfaces are also described as "protocol buffer services" in some contexts,

6087

# such as by the "service" keyword in a .proto file, but they are different

6088

# from API Services, which represent a concrete implementation of an interface

6089

# as opposed to simply a description of methods and bindings. They are also

6090

# sometimes simply referred to as "APIs" in other contexts, such as the name of

6091

# this message itself. See https://cloud.google.com/apis/design/glossary for

6092

# detailed terminology.

6093

"methods": [ # The methods of this interface, in unspecified order.

6094

{ # Method represents a method of an API interface.

6095

"name": "A String", # The simple name of this method.

6096

"requestStreaming": True or False, # If true, the request is streamed.

6097

"responseTypeUrl": "A String", # The URL of the output message type.

6098

"requestTypeUrl": "A String", # A URL of the input message type.

6099

"responseStreaming": True or False, # If true, the response is streamed.

6100

"syntax": "A String", # The source syntax of this method.

6101

"options": [ # Any metadata attached to the method.

6102

{ # A protocol buffer option, which can be attached to a message, field,

6103

# enumeration, etc.

6104

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6105

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6106

# For custom options, it should be the fully-qualified name. For example,

6107

# `"google.api.http"`.

6108

"value": { # The option's value packed in an Any message. If the value is a primitive,

6109

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6110

# should be used. If the value is an enum, it should be stored as an int32

6111

# value using the google.protobuf.Int32Value type.

6112

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6118

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

6119

# message.

6120

# protobuf element, like the file in which it is defined.

6121

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6122

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6123

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6124

"mixins": [ # Included interfaces. See Mixin.

6125

{ # Declares an API Interface to be included in this interface. The including

6126

# interface must redeclare all the methods from the included interface, but

6127

# documentation and options are inherited as follows:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6128

#

6129

# - If after comment and whitespace stripping, the documentation

6130

# string of the redeclared method is empty, it will be inherited

6131

# from the original method.

6132

#

6133

# - Each annotation belonging to the service config (http,

6134

# visibility) which is not set in the redeclared method will be

6135

# inherited.

6136

#

6137

# - If an http annotation is inherited, the path pattern will be

6138

# modified as follows. Any version prefix will be replaced by the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6139

# version of the including interface plus the root path if

6140

# specified.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6141

#

6142

# Example of a simple mixin:

6143

#

6144

# package google.acl.v1;

6145

# service AccessControl {

6146

# // Get the underlying ACL object.

6147

# rpc GetAcl(GetAclRequest) returns (Acl) {

6148

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

6153

# service Storage {

6154

# // rpc GetAcl(GetAclRequest) returns (Acl);

6155

#

6156

# // Get a data record.

6157

# rpc GetData(GetDataRequest) returns (Data) {

6158

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

6163

#

6164

# apis:

6165

# - name: google.storage.v2.Storage

6166

# mixins:

6167

# - name: google.acl.v1.AccessControl

6168

#

6169

# The mixin construct implies that all methods in `AccessControl` are

6170

# also declared with same name and request/response types in

6171

# `Storage`. A documentation generator or annotation processor will

6172

# see the effective `Storage.GetAcl` method after inherting

6173

# documentation and annotations as follows:

6174

#

6175

# service Storage {

6176

# // Get the underlying ACL object.

6177

# rpc GetAcl(GetAclRequest) returns (Acl) {

6178

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

6184

#

6185

# If the `root` field in the mixin is specified, it should be a

6186

# relative path under which inherited HTTP paths are placed. Example:

6187

#

6188

# apis:

6189

# - name: google.storage.v2.Storage

6190

# mixins:

6191

# - name: google.acl.v1.AccessControl

6192

# root: acls

6193

#

6194

# This implies the following inherited HTTP annotation:

6195

#

6196

# service Storage {

6197

# // Get the underlying ACL object.

6198

# rpc GetAcl(GetAclRequest) returns (Acl) {

6199

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

6204

# are rooted.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6205

"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]

6206

},

6207

],

6208

"syntax": "A String", # The source syntax of the service.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6209

"version": "A String", # A version string for this interface. If specified, must have the form

6210

# `major-version.minor-version`, as in `1.10`. If the minor version is

6211

# omitted, it defaults to zero. If the entire version field is empty, the

6212

# major version is derived from the package name, as outlined below. If the

6213

# field is not empty, the version in the package name will be verified to be

6214

# consistent with what is provided here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6215

#

6216

# The versioning schema uses [semantic

6217

# versioning](http://semver.org) where the major version number

6218

# indicates a breaking change and the minor version an additive,

6219

# non-breaking change. Both version numbers are signals to users

6220

# what to expect from different versions, and should be carefully

6221

# chosen based on the product plan.

6222

#

6223

# The major version is also reflected in the package name of the

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6224

# interface, which must end in `v<major-version>`, as in

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6225

# `google.feature.v1`. For major versions 0 and 1, the suffix can

6226

# be omitted. Zero major versions must only be used for

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6227

# experimental, non-GA interfaces.

6228

"options": [ # Any metadata attached to the interface.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6229

{ # A protocol buffer option, which can be attached to a message, field,

6230

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6231

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6232

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6233

# For custom options, it should be the fully-qualified name. For example,

6234

# `"google.api.http"`.

6235

"value": { # The option's value packed in an Any message. If the value is a primitive,

6236

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6237

# should be used. If the value is an enum, it should be stored as an int32

6238

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6239

"a_key": "", # Properties of the object. Contains field @type with type URL.

6240

},

6241

},

6242

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6243

"name": "A String", # The fully qualified name of this interface, including package name

6244

# followed by the interface's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6245

},

6246

],

6247

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

6248

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

6256

# - google.foo.v1.AnotherError

6257

"rules": [ # The list of custom error rules that apply to individual API messages.

6258

#

6259

# **NOTE:** All service configuration rules follow "last one wins" order.

6260

{ # A custom error rule.

6261

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

6262

# objects of this type will be filtered when they appear in error payload.

6263

"selector": "A String", # Selects messages to which this rule applies.

6264

#

6265

# Refer to selector for syntax details.

6266

},

6267

],

6268

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

6269

"A String",

6270

],

6271

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6272

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

6273

# usage.

6274

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6275

# The metric based quota configuration works this way:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6276

# - The service configuration defines a set of metrics.

6277

# - For API calls, the quota.metric_rules maps methods to metrics with

6278

# corresponding costs.

6279

# - The quota.limits defines limits on the metrics, which will be used for

6280

# quota checks at runtime.

6281

#

6282

# An example quota configuration in yaml format:

6283

#

6284

# quota:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6285

# limits:

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6286

#

6287

# - name: apiWriteQpsPerProject

6288

# metric: library.googleapis.com/write_calls

6289

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

6295

# # except for the UpdateBook and DeleteBook methods. These two methods

6296

# # are mapped to the write_calls metric, with the UpdateBook method

6297

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

6302

# - selector: google.example.library.v1.LibraryService.UpdateBook

6303

# metric_costs:

6304

# library.googleapis.com/write_calls: 2

6305

# - selector: google.example.library.v1.LibraryService.DeleteBook

6306

# metric_costs:

6307

# library.googleapis.com/write_calls: 1

6308

#

6309

# Corresponding Metric definition:

6310

#

6311

# metrics:

6312

# - name: library.googleapis.com/read_calls

6313

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

6318

# display_name: Write requests

6319

# metric_kind: DELTA

6320

# value_type: INT64

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6321

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6322

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

6323

# or more metrics.

6324

{ # Bind API methods to metrics. Binding a method to a metric causes that

6325

# metric's configured quota behaviors to apply to the method call.

6326

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

6327

# cost applied to each metric.

6328

#

6329

# The key of the map is the metric name, and the values are the amount

6330

# increased for the metric against which the quota limits are defined.

6331

# The value must not be negative.

6332

"a_key": "A String",

6333

},

6334

"selector": "A String", # Selects the methods to which this rule applies.

6335

#

6336

# Refer to selector for syntax details.

6337

},

6338

],

6339

"limits": [ # List of `QuotaLimit` definitions for the service.

6340

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

6341

# for a limit type. There can be at most one limit for a duration and limit

6342

# type combination defined within a `QuotaGroup`.

6343

"displayName": "A String", # User-visible display name for this limit.

6344

# Optional. If not set, the UI will provide a default display name based on

6345

# the quota configuration. This field can be used to override the default

6346

# display name generated from the configuration.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6347

"name": "A String", # Name of the quota limit.

6348

#

6349

# The name must be provided, and it must be unique within the service. The

6350

# name can only include alphanumeric characters as well as '-'.

6351

#

6352

# The maximum length of the limit name is 64 characters.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6353

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

6354

# duration. This is the number of tokens assigned when a client

6355

# application developer activates the service for his/her project.

6356

#

6357

# Specifying a value of 0 will block all requests. This can be used if you

6358

# are provisioning quota to selected consumers and blocking others.

6359

# Similarly, a value of -1 will indicate an unlimited quota. No other

6360

# negative values are allowed.

6361

#

6362

# Used by group-based quotas only.

6363

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

6364

# the same metric will be checked together during runtime. The metric must be

6365

# defined within the service config.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6366

"values": { # Tiered limit values. You must specify this as a key:value pair, with an

6367

# integer value that is the maximum number of requests allowed for the

6368

# specified unit. Currently only STANDARD is supported.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6369

"a_key": "A String",

6370

},

6371

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

6372

# duration. Client application developers can override the default limit up

6373

# to this maximum. If specified, this value cannot be set to a value less

6374

# than the default limit. If not specified, it is set to the default limit.

6375

#

6376

# To allow clients to apply overrides with no upper bound, set this to -1,

6377

# indicating unlimited maximum quota.

6378

#

6379

# Used by group-based quotas only.

6380

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

6381

# For duration longer than a day, only multiple of days is supported. We

6382

# support only "100s" and "1d" for now. Additional support will be added in

6383

# the future. "0" indicates indefinite duration.

6384

#

6385

# Used by group-based quotas only.

6386

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

6387

# The free tier is the number of tokens that will be subtracted from the

6388

# billed amount when billing is enabled.

6389

# This field can only be set on a limit with duration "1d", in a billable

6390

# group; it is invalid on any other limit. If this field is not set, it

6391

# defaults to 0, indicating that there is no free tier for this service.

6392

#

6393

# Used by group-based quotas only.

6394

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

6395

# Metric.unit. The supported unit kinds are determined by the quota

6396

# backend system.

6397

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6398

# Here are some examples:

6399

# * "1/min/{project}" for quota per minute per project.

6400

#

6401

# Note: the order of unit components is insignificant.

6402

# The "1" at the beginning is required to follow the metric unit syntax.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6403

"description": "A String", # Optional. User-visible, extended description for this quota limit.

6404

# Should be used only when more context is needed to understand this limit

6405

# than provided by the limit's display name (see: `display_name`).

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]

6410

{ # Defines a metric type and its schema. Once a metric descriptor is created,

6411

# deleting or altering it stops data collection and makes the metric type's

6412

# existing data unusable.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6413

"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]

6414

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

6415

# Use sentence case without an ending period, for example "Request count".

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6416

# This field is optional but it is recommended to be set for any metrics

6417

# associated with user-visible concepts, such as Quota.

6418

"name": "A String", # The resource name of the metric descriptor.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6419

"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]

6420

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6421

"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]

6422

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6423

"labels": [ # The set of labels that can be used to describe a specific

6424

# instance of this metric type. For example, the

6425

# `appengine.googleapis.com/http/server/response_latencies` metric

6426

# type has a label for the HTTP response code, `response_code`, so

6427

# you can look at latencies for successful responses or just

6428

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6429

{ # A description of a label.

6430

"valueType": "A String", # The type of data that can be assigned to the label.

6431

"description": "A String", # A human-readable description for the label.

6432

"key": "A String", # The label key.

6433

},

6434

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6435

"launchStage": "A String", # Optional. The launch stage of the metric definition.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6436

"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^]

6437

# URL-encoded. All user-defined metric types have the DNS name

6438

# `custom.googleapis.com` or `external.googleapis.com`. Metric types should

6439

# use a natural hierarchical grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6440

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6441

# "custom.googleapis.com/invoice/paid/amount"

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6442

# "external.googleapis.com/prometheus/up"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6443

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6444

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

6445

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

6446

# supported units are a subset of [The Unified Code for Units of

6447

# Measure](http://unitsofmeasure.org/ucum.html) standard:

6448

#

6449

# **Basic units (UNIT)**

#

# * `bit` bit

# * `By` byte

# * `s` second

# * `min` minute

# * `h` hour

# * `d` day

#

# **Prefixes (PREFIX)**

#

# * `k` kilo (10**3)

# * `M` mega (10**6)

# * `G` giga (10**9)

# * `T` tera (10**12)

6464

# * `P` peta (10**15)

6465

# * `E` exa (10**18)

6466

# * `Z` zetta (10**21)

6467

# * `Y` yotta (10**24)

6468

# * `m` milli (10**-3)

6469

# * `u` micro (10**-6)

6470

# * `n` nano (10**-9)

6471

# * `p` pico (10**-12)

6472

# * `f` femto (10**-15)

6473

# * `a` atto (10**-18)

6474

# * `z` zepto (10**-21)

6475

# * `y` yocto (10**-24)

6476

# * `Ki` kibi (2**10)

6477

# * `Mi` mebi (2**20)

6478

# * `Gi` gibi (2**30)

6479

# * `Ti` tebi (2**40)

6480

#

6481

# **Grammar**

6482

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6483

# The grammar also includes these connectors:

6484

#

6485

# * `/` division (as an infix operator, e.g. `1/s`).

6486

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

6487

#

6488

# The grammar for a unit is as follows:

6489

#

6490

# Expression = Component { "." Component } { "/" Component } ;

6491

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6492

# Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

6502

# equivalent to `1` if it is used alone. For examples,

6503

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

6504

# * `NAME` is a sequence of non-blank printable ASCII characters not

6505

# containing '{' or '}'.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6506

# * `1` represents dimensionless value 1, such as in `1/s`.

6507

# * `%` represents dimensionless value 1/100, and annotates values giving

6508

# a percentage.

6509

"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.

6510

"launchStage": "A String", # Deprecated. Please use the MetricDescriptor.launch_stage instead.

6511

# The launch stage of the metric definition.

6512

"ingestDelay": "A String", # The delay of data points caused by ingestion. Data points older than this

6513

# age are guaranteed to be ingested and available to be read, excluding

6514

# data loss due to errors.

6515

"samplePeriod": "A String", # The sampling period of metric data points. For metrics which are written

6516

# periodically, consecutive data points are stored at this time interval,

6517

# excluding data loss due to errors. Metrics with a higher granularity have

6518

# a smaller sampling period.

6519

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6520

},

6521

],

6522

"enums": [ # A list of all enum types included in this API service. Enums

6523

# referenced directly or indirectly by the `apis` are automatically

6524

# included. Enums which are not referenced but shall be included

6525

# should be listed here by name. Example:

6526

#

6527

# enums:

6528

# - name: google.someapi.v1.SomeEnum

6529

{ # Enum type definition.

6530

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6531

# protobuf element, like the file in which it is defined.

6532

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6533

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6534

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6535

"enumvalue": [ # Enum value definitions.

6536

{ # Enum value definition.

6537

"options": [ # Protocol buffer options.

6538

{ # A protocol buffer option, which can be attached to a message, field,

6539

# enumeration, etc.

6540

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6541

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6542

# For custom options, it should be the fully-qualified name. For example,

6543

# `"google.api.http"`.

6544

"value": { # The option's value packed in an Any message. If the value is a primitive,

6545

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6546

# should be used. If the value is an enum, it should be stored as an int32

6547

# value using the google.protobuf.Int32Value type.

6548

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

6553

"number": 42, # Enum value number.

6554

},

6555

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6556

"options": [ # Protocol buffer options.

6557

{ # A protocol buffer option, which can be attached to a message, field,

6558

# enumeration, etc.

6559

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6560

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6561

# For custom options, it should be the fully-qualified name. For example,

6562

# `"google.api.http"`.

6563

"value": { # The option's value packed in an Any message. If the value is a primitive,

6564

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6565

# should be used. If the value is an enum, it should be stored as an int32

6566

# value using the google.protobuf.Int32Value type.

6567

"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]

6572

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6573

},

6574

],

6575

"types": [ # A list of all proto message types included in this API service.

6576

# Types referenced directly or indirectly by the `apis` are

6577

# automatically included. Messages which are not referenced but

6578

# shall be included, such as types used by the `google.protobuf.Any` type,

6579

# should be listed here by name. Example:

6580

#

6581

# types:

6582

# - name: google.protobuf.Int32

6583

{ # A protocol buffer message type.

6584

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6585

"A String",

6586

],

6587

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6588

"fields": [ # The list of fields.

6589

{ # A single field of a message type.

6590

"kind": "A String", # The field type.

6591

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6592

# types. The first type has index 1; zero means the type is not in the list.

6593

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6594

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6595

"name": "A String", # The field name.

6596

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6597

"jsonName": "A String", # The field JSON name.

6598

"number": 42, # The field number.

6599

"cardinality": "A String", # The field cardinality.

6600

"options": [ # The protocol buffer options.

6601

{ # A protocol buffer option, which can be attached to a message, field,

6602

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6603

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6604

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6605

# For custom options, it should be the fully-qualified name. For example,

6606

# `"google.api.http"`.

6607

"value": { # The option's value packed in an Any message. If the value is a primitive,

6608

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6609

# should be used. If the value is an enum, it should be stored as an int32

6610

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6611

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

6616

},

6617

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6618

"syntax": "A String", # The source syntax.

6619

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6620

# protobuf element, like the file in which it is defined.

6621

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6622

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6623

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6624

"options": [ # The protocol buffer options.

6625

{ # A protocol buffer option, which can be attached to a message, field,

6626

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6627

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6628

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6629

# For custom options, it should be the fully-qualified name. For example,

6630

# `"google.api.http"`.

6631

"value": { # The option's value packed in an Any message. If the value is a primitive,

6632

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6633

# should be used. If the value is an enum, it should be stored as an int32

6634

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6635

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6641

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6642

#

6643

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6644

# producer and consumer projects. In the example, the `activity_history`

6645

# log is sent to both the producer and consumer projects, whereas the

6646

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6647

#

6648

# monitored_resources:

6649

# - type: library.googleapis.com/branch

6650

# labels:

6651

# - key: /city

6652

# description: The city where the library branch is located in.

6653

# - key: /name

6654

# description: The name of the branch.

6655

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6656

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6657

# labels:

6658

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6659

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6660

# logging:

6661

# producer_destinations:

6662

# - monitored_resource: library.googleapis.com/branch

6663

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6664

# - activity_history

6665

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6666

# consumer_destinations:

6667

# - monitored_resource: library.googleapis.com/branch

6668

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6669

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6670

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

6671

# There can be multiple producer destinations, each one must have a

6672

# different monitored resource type. A log can be used in at most

6673

# one producer destination.

6674

{ # Configuration of a specific logging destination (the producer project

6675

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6676

"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]

6677

# Service.monitored_resources section.

6678

"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]

6679

# be defined in the Service.logs section. If the log name is

6680

# not a domain scoped name, it will be automatically prefixed with

6681

# 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.

6687

# There can be multiple consumer destinations, each one must have a

6688

# different monitored resource type. A log can be used in at most

6689

# one consumer destination.

6690

{ # Configuration of a specific logging destination (the producer project

6691

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6692

"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]

6693

# Service.monitored_resources section.

6694

"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]

6695

# be defined in the Service.logs section. If the log name is

6696

# not a domain scoped name, it will be automatically prefixed with

6697

# 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^]

6703

"name": "A String", # The service name, which is a DNS-like logical identifier for the

6704

# service, such as `calendar.googleapis.com`. The service name

6705

# typically goes through DNS verification to make sure the owner

6706

# of the service also owns the DNS name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6707

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

6708

#

6709

# Example:

6710

# <pre><code>documentation:

6711

# summary: >

6712

# The Google Calendar API gives access

6713

# to most calendar features.

6714

# pages:

6715

# - name: Overview

6716

# content: (== include google/foo/overview.md ==)

6717

# - name: Tutorial

6718

# content: (== include google/foo/tutorial.md ==)

6719

# subpages;

6720

# - name: Java

6721

# content: (== include google/foo/tutorial_java.md ==)

6722

# rules:

6723

# - selector: google.calendar.Calendar.Get

6724

# description: >

6725

# ...

6726

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

6731

# standard markdown features, definition lists, tables and fenced

6732

# code blocks are supported. Section headers can be provided and are

6733

# interpreted relative to the section nesting of the context where

6734

# a documentation fragment is embedded.

6735

#

6736

# Documentation from the IDL is merged with documentation defined

6737

# via the config at normalization time, where documentation provided

6738

# by config rules overrides IDL provided.

6739

#

6740

# A number of constructs specific to the API platform are supported

6741

# in documentation text.

6742

#

6743

# In order to reference a proto element, the following

6744

# notation can be used:

6745

# <pre><code>[fully.qualified.proto.name][]</code></pre>

6746

# To override the display text used for the link, this can be used:

6747

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

6748

# Text can be excluded from doc using the following notation:

6749

# <pre><code>(-- internal comment --)</code></pre>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6750

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6751

# A few directives are available in documentation. Note that

6752

# directives must appear on a single line to be properly

6753

# identified. The `include` directive includes a markdown file from

6754

# an external source:

6755

# <pre><code>(== include path/to/file ==)</code></pre>

6756

# The `resource_for` directive marks a message to be the resource of

6757

# a collection in REST view. If it is not specified, tools attempt

6758

# to infer the resource from the operations in a collection:

6759

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

6760

# The directive `suppress_warning` does not directly affect documentation

6761

# and is documented together with service config validation.

6762

"rules": [ # A list of documentation rules that apply to individual API elements.

6763

#

6764

# **NOTE:** All service configuration rules follow "last one wins" order.

6765

{ # A documentation rule provides information about individual API elements.

6766

"description": "A String", # Description of the selected API(s).

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6767

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if

6768

# an element is marked as `deprecated`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6769

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

6770

# qualified name of the element which may end in "*", indicating a wildcard.

6771

# 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^]

6772

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A

6773

# wildcard will match one or more components. To specify a default for all

6774

# applicable elements, the whole pattern "*" is used.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6775

},

6776

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6777

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

6778

"overview": "A String", # Declares a single overview page. For example:

6779

# <pre><code>documentation:

6780

# summary: ...

6781

# overview: (== include overview.md ==)

6782

# </code></pre>

6783

# This is a shortcut for the following declaration (using pages style):

6784

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

6789

# </code></pre>

6790

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6791

"pages": [ # The top level pages for the documentation set.

6792

{ # Represents a documentation page. A page can contain subpages to represent

6793

# nested documentation set structure.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6794

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path}

6795

# ==)</code> to include content from a Markdown file.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6796

"subpages": [ # Subpages of this page. The order of subpages specified here will be

6797

# honored in the generated docset.

6798

# Object with schema name: Page

6799

],

6800

"name": "A String", # The name of the page. It will be used as an identity of the page to

6801

# generate URI of the page, text of the link to this page in navigation,

6802

# etc. The full page name (start from the root page name to this page

6803

# concatenated with `.`) can be used as reference to the page in your

6804

# documentation. For example:

6805

# <pre><code>pages:

6806

# - name: Tutorial

6807

# content: (== include tutorial.md ==)

6808

# subpages:

6809

# - name: Java

6810

# content: (== include tutorial_java.md ==)

6811

# </code></pre>

6812

# You can reference `Java` page using Markdown reference link syntax:

6813

# `Java`.

6814

},

6815

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

6816

"summary": "A String", # A short summary of what the service does. Can only be provided by

6817

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6818

},

6819

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

6820

"sourceFiles": [ # All files used during config generation.

6821

{

6822

"a_key": "", # Properties of the object. Contains field @type with type URL.

6823

},

6824

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6825

},

6826

"systemTypes": [ # A list of all proto message types included in this API service.

6827

# It serves similar purpose as [google.api.Service.types], except that

6828

# these types are not needed by user-defined APIs. Therefore, they will not

6829

# show up in the generated discovery doc. This field should only be used

6830

# to define system APIs in ESF.

6831

{ # A protocol buffer message type.

6832

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6833

"A String",

6834

],

6835

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6836

"fields": [ # The list of fields.

6837

{ # A single field of a message type.

6838

"kind": "A String", # The field type.

6839

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6840

# types. The first type has index 1; zero means the type is not in the list.

6841

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6842

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6843

"name": "A String", # The field name.

6844

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6845

"jsonName": "A String", # The field JSON name.

6846

"number": 42, # The field number.

6847

"cardinality": "A String", # The field cardinality.

6848

"options": [ # The protocol buffer options.

6849

{ # A protocol buffer option, which can be attached to a message, field,

6850

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6851

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6852

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6853

# For custom options, it should be the fully-qualified name. For example,

6854

# `"google.api.http"`.

6855

"value": { # The option's value packed in an Any message. If the value is a primitive,

6856

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6857

# should be used. If the value is an enum, it should be stored as an int32

6858

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6859

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

6864

},

6865

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6866

"syntax": "A String", # The source syntax.

6867

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6868

# protobuf element, like the file in which it is defined.

6869

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6870

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6871

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6872

"options": [ # The protocol buffer options.

6873

{ # A protocol buffer option, which can be attached to a message, field,

6874

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6875

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6876

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6877

# For custom options, it should be the fully-qualified name. For example,

6878

# `"google.api.http"`.

6879

"value": { # The option's value packed in an Any message. If the value is a primitive,

6880

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6881

# should be used. If the value is an enum, it should be stored as an int32

6882

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6883

"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

6898

# - google.rpc.context.OriginContext

6899

#

6900

# The above specifies that all methods in the API request

6901

# `google.rpc.context.ProjectContext` and

6902

# `google.rpc.context.OriginContext`.

6903

#

6904

# Available context types are defined in package

6905

# `google.rpc.context`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6906

#

6907

# This also provides mechanism to whitelist any protobuf message extension that

6908

# can be sent in grpc metadata using “x-goog-ext-<extension_id>-bin” and

6909

# “x-goog-ext-<extension_id>-jspb” format. For example, list any service

6910

# 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"

6918

# allowed_request_extensions:

6919

# - google.foo.v1.NewExtension

6920

# allowed_response_extensions:

6921

# - google.foo.v1.NewExtension

6922

#

6923

# You can also specify extension ID instead of fully qualified extension name

6924

# here.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6925

"rules": [ # A list of RPC context rules that apply to individual API methods.

6926

#

6927

# **NOTE:** All service configuration rules follow "last one wins" order.

6928

{ # A context rule provides information about the context for an individual API

6929

# element.

6930

"provided": [ # A list of full type names of provided contexts.

6931

"A String",

6932

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6933

"allowedResponseExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

6934

# side channel from backend to client.

6935

"A String",

6936

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6937

"selector": "A String", # Selects the methods to which this rule applies.

6938

#

6939

# Refer to selector for syntax details.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6940

"allowedRequestExtensions": [ # A list of full type names or extension IDs of extensions allowed in grpc

6941

# side channel from client to backend.

6942

"A String",

6943

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6944

"requested": [ # A list of full type names of requested contexts.

6945

"A String",

6946

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6947

},

6948

],

6949

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6950

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

6951

# with the same name as the service is automatically generated to service all

6952

# defined APIs.

6953

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

6954

# A service may expose any number of endpoints, and all endpoints share the

6955

# same service configuration, such as quota configuration and monitoring

6956

# configuration.

6957

#

6958

# Example service configuration:

6959

#

6960

# name: library-example.googleapis.com

6961

# endpoints:

6962

# # Below entry makes 'google.example.library.v1.Library'

6963

# # API be served from endpoint address library-example.googleapis.com.

6964

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

6965

# # it to decide whether the subsequent cross-origin request is

6966

# # allowed to proceed.

6967

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6968

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6969

"allowCors": True or False, # Allowing

6970

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

6971

# cross-domain traffic, would allow the backends served from this endpoint to

6972

# receive and respond to HTTP OPTIONS requests. The response will be used by

6973

# the browser to determine whether the subsequent cross-origin request is

6974

# allowed to proceed.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6975

"target": "A String", # The specification of an Internet routable address of API frontend that will

6976

# handle requests to this [API

6977

# Endpoint](https://cloud.google.com/apis/design/glossary). It should be

6978

# either a valid IPv4 address or a fully-qualified domain name. For example,

6979

# "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6980

"features": [ # The list of features enabled on this endpoint.

6981

"A String",

6982

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6983

"name": "A String", # The canonical name of this endpoint.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6984

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

6985

# please specify multiple google.api.Endpoint for each of the intended

6986

# aliases.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6987

#

6988

# 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>

7000

<pre>Retrieves the next page of results.

7001

7002

Args:

7003

previous_request: The request for the previous page. (required)

7004

previous_response: The response from the request for the previous page. (required)

7005

7006

Returns:

7007

A request object that you can call 'execute()' on to request the next

7008

page. Returns None if there are no more items in the collection.

</pre>

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7013

<code class="details" id="submit">submit(serviceName, body, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7014

<pre>Creates a new service configuration (version) for a managed service based

7015

on

7016

user-supplied configuration source files (for example: OpenAPI

7017

Specification). This method stores the source configurations as well as the

7018

generated service configuration. To rollout the service configuration to

7019

other services,

7020

please call CreateServiceRollout.

7021

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame^]

7022

Only the 100 most recent configuration sources and ones referenced by

7023

existing service configurtions are kept for each service. The rest will be

7024

deleted eventually.

7025

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7026

Operation<response: SubmitConfigSourceResponse>

7027

7028

Args:

7029

serviceName: string, The name of the service. See the [overview](/service-management/overview)

7030

for naming requirements. For example: `example.googleapis.com`. (required)

7031

body: object, The request body. (required)

7032

The object takes the form of:

7033

7034

{ # Request message for SubmitConfigSource method.

7035

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7036

# `google.api.Service` configuration based on the `ConfigSource` provided,

7037

# but the generated config and the sources will NOT be persisted.

7038

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

7039

# defined by `google.api.Service`.

7040

"files": [ # Set of source configuration files that are used to generate a service

7041

# configuration (`google.api.Service`).

7042

{ # Generic specification of a source configuration file

7043

"fileContents": "A String", # The bytes that constitute the file.

7044

"fileType": "A String", # The type of configuration file this represents.

7045

"filePath": "A String", # The file name of the configuration file (full or relative path).

7046

},

7047

],

7048

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7049

# by the client for tracking purpose. If empty, the server may choose to

7050

# 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:

7061

7062

{ # This resource represents a long-running operation that is the result of a

7063

# network API call.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7064

"response": { # The normal response of the operation in case of success. If the original

7065

# method returns no data on success, such as `Delete`, the response is

7066

# `google.protobuf.Empty`. If the original method is standard

7067

# `Get`/`Create`/`Update`, the response should be the resource. For other

7068

# methods, the response should have the type `XxxResponse`, where `Xxx`

7069

# is the original method name. For example, if the original method name

7070

# is `TakeSnapshot()`, the inferred response type is

7071

# `TakeSnapshotResponse`.

7072

"a_key": "", # Properties of the object. Contains field @type with type URL.

7073

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7074

"metadata": { # Service-specific metadata associated with the operation. It typically

7075

# contains progress information and common metadata such as create time.

7076

# Some services might not provide such metadata. Any method that returns a

7077

# long-running operation should document the metadata type, if any.

7078

"a_key": "", # Properties of the object. Contains field @type with type URL.

7079

},

Bu Sun Kim