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

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

100

Args:

101

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

102

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

103

body: object, The request body. (required)

104

The object takes the form of:

105

Sai Cheemalapati

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

[diff] [blame]

106

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

107

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

108

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

109

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

110

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

115

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

116

# name: calendar.googleapis.com

117

# title: Google Calendar API

118

# apis:

Sai Cheemalapati

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

[diff] [blame]

119

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame]

120

# authentication:

121

# providers:

122

# - id: google_calendar_auth

123

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

124

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

Jon Wayne Parrott

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

[diff] [blame]

125

# rules:

Jon Wayne Parrott

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

[diff] [blame]

126

# - selector: "*"

127

# requirements:

128

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

129

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

130

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

131

# monitoring, etc.

132

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

133

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

134

},

135

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

136

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

137

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

138

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

139

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

140

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

141

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

142

#

143

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

144

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

145

# by the API.

Thomas Coffee

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

[diff] [blame]

146

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

147

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

148

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

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

[diff] [blame]

149

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

150

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

151

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

152

{ # A description of a label.

153

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

154

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

155

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

156

},

157

],

Thomas Coffee

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

[diff] [blame]

158

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

159

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

160

# without any article or other determiners. For example,

161

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

162

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

163

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

164

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

165

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

166

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

167

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

Sai Cheemalapati

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

[diff] [blame]

168

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

169

# be used in documentation.

Jon Wayne Parrott

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

[diff] [blame]

170

},

171

],

172

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

173

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

174

#

175

# - name: library.googleapis.com/activity_history

176

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

177

# display_name: Activity

178

# labels:

179

# - key: /customer_id

180

# description: Identifier of a library customer

181

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

182

# Runtime requests that contain labels not specified here are

183

# considered invalid.

184

{ # A description of a label.

185

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

186

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

187

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

188

},

189

],

190

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

191

# the user interface and should be concise.

Jon Wayne Parrott

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

[diff] [blame]

192

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

193

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

194

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

195

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

Thomas Coffee

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

[diff] [blame]

196

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

197

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

198

},

199

],

Thomas Coffee

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

[diff] [blame]

200

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

201

#

202

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

203

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

204

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

205

# change the names of the system parameters.

206

"rules": [ # Define system parameters.

207

#

208

# The parameters defined here will override the default parameters

209

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

210

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

211

# and names is implementation-dependent.

212

#

213

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

221

#

222

#

223

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

228

# parameters:

229

# - name: api_key

230

# http_header: Api-Key1

231

# - name: api_key

232

# http_header: Api-Key2

233

#

234

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

235

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

236

# methods.

237

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

238

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

239

# names are used the behavior is implementation-dependent.

240

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

241

# parameter-dependent.

242

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

243

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

244

# is implementation-dependent.

245

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

246

# sensitive.

247

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

248

# insensitive.

249

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

250

},

251

],

252

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

253

# methods in all APIs.

254

#

255

# Refer to selector for syntax details.

256

},

257

],

258

},

Sai Cheemalapati

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

[diff] [blame]

259

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

260

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

261

# generate one instead.

Jon Wayne Parrott

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

[diff] [blame]

262

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

263

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

264

#

265

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

266

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

267

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

268

#

269

# Refer to selector for syntax details.

Sai Cheemalapati

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

[diff] [blame]

270

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

271

# value lower than this will be rejected.

Jon Wayne Parrott

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

[diff] [blame]

272

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

273

# default depends on the deployment context.

274

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

275

},

276

],

277

},

Sai Cheemalapati

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

[diff] [blame]

278

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

Jon Wayne Parrott

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

[diff] [blame]

279

#

280

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

281

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

282

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

283

# to both producer and consumer projects, whereas the

284

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

285

# consumer project.

286

#

287

# monitored_resources:

288

# - type: library.googleapis.com/branch

289

# labels:

290

# - key: /city

291

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

292

# - key: /name

293

# description: The name of the branch.

294

# metrics:

295

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

300

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

305

# monitoring:

306

# producer_destinations:

307

# - monitored_resource: library.googleapis.com/branch

308

# metrics:

309

# - library.googleapis.com/book/returned_count

310

# consumer_destinations:

311

# - monitored_resource: library.googleapis.com/branch

312

# metrics:

313

# - library.googleapis.com/book/returned_count

314

# - library.googleapis.com/book/overdue_count

315

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

316

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

317

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

318

# one producer destination.

319

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

320

# or the consumer project).

321

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

322

# Service.monitored_resources section.

323

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

324

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

"A String",

],

},

],

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

330

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

331

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

332

# one consumer destination.

333

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

334

# or the consumer project).

335

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

336

# Service.monitored_resources section.

337

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

338

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

"A String",

],

},

],

},

Thomas Coffee

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

[diff] [blame]

344

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

Jon Wayne Parrott

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

[diff] [blame]

345

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

346

#

347

# Example for an API targeted for external use:

348

#

349

# name: calendar.googleapis.com

350

# authentication:

Jon Wayne Parrott

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

[diff] [blame]

351

# providers:

352

# - id: google_calendar_auth

353

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

354

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

Jon Wayne Parrott

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

[diff] [blame]

355

# rules:

356

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame]

357

# requirements:

358

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

359

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

360

#

361

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

362

{ # Authentication rules for the service.

363

#

364

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

365

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

366

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

367

# request.

368

#

369

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

370

# ignored.

371

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

372

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

373

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

374

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

375

#

376

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

377

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

378

#

379

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

380

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

381

# the OAuth scope across all of those APIs.

382

#

383

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

384

# management about how developers will use them in practice.

385

#

386

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

387

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

388

# due to the backend requiring additional scopes or permissions.

389

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

390

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

#

# Example:

#

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

395

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

396

},

397

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

398

{ # User-defined authentication requirements, including support for

399

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

400

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame]

405

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

406

# implemented and accepted in all the runtime components.

407

#

408

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

409

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

410

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

411

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

412

# "https://Service_name/API_name"

413

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

414

# LibraryService API will only accept JWTs with the following audience

415

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

420

# bookstore_web.apps.googleusercontent.com

421

},

422

],

Sai Cheemalapati

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

[diff] [blame]

423

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

424

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

425

#

426

# For requests without credentials, if the service control environment is

427

# specified, each incoming request **must** be associated with a service

428

# consumer. This can be done by passing an API key that belongs to a consumer

429

# project.

430

"customAuth": { # Configuration for a custom authentication provider. # Configuration for custom authentication.

431

"provider": "A String", # A configuration string containing connection information for the

432

# authentication provider, typically formatted as a SmartService string

433

# (go/smartservice).

434

},

Jon Wayne Parrott

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

[diff] [blame]

435

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

436

#

437

# Refer to selector for syntax details.

438

},

439

],

440

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

441

{ # Configuration for an anthentication provider, including support for

442

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

Jon Wayne Parrott

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

[diff] [blame]

443

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

444

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

445

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

446

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

447

# "https://Service_name/API_name"

448

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

449

# LibraryService API will only accept JWTs with the following audience

450

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

455

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

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

[diff] [blame]

456

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

457

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

458

# Optional if the key set document:

459

# - can be retrieved from

460

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

461

# of the issuer.

462

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

463

#

464

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

Jon Wayne Parrott

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

[diff] [blame]

465

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

466

# `AuthRequirement.provider_id`.

467

#

468

# Example: "bookstore_auth".

469

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

470

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

471

# Usually a URL or an email address.

472

#

473

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

474

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

},

],

},

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

479

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

480

#

481

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

482

{ # Usage configuration rules for the service.

483

#

484

# NOTE: Under development.

485

#

486

#

487

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

488

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

489

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

490

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

491

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

492

# allow/disallow unregistered calls.

493

#

494

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

500

#

501

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

#

# usage:

# rules:

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

506

# allow_unregistered_calls: true

Sai Cheemalapati

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

[diff] [blame]

507

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

Jon Wayne Parrott

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

[diff] [blame]

508

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

509

# methods in all APIs.

510

#

511

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

512

},

513

],

Jon Wayne Parrott

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

[diff] [blame]

514

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

515

# service producer.

516

#

517

# Google Service Management currently only supports

518

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

519

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

520

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

521

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

Jon Wayne Parrott

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

[diff] [blame]

522

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

523

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

524

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

"A String",

],

},

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

529

# influence interpretation of the configuration, for example, to

530

# determine defaults. This is documented together with applicable

531

# options. The current default for the config version itself is `3`.

532

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

533

# Members of this project can manage the service configuration,

534

# manage consumption of the service, etc.

535

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

536

# HttpRule, each specifying the mapping of an RPC method

537

# to one or more HTTP REST API methods.

538

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

539

#

540

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

541

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

542

# REST APIs. The mapping determines what portions of the request

543

# message are populated from the path, query parameters, or body of

544

# the HTTP request. The mapping is typically specified as an

545

# `google.api.http` annotation, see "google/api/annotations.proto"

546

# for details.

547

#

548

# The mapping consists of a field specifying the path template and

549

# method kind. The path template can refer to fields in the request

550

# message, as in the example below which describes a REST GET

551

# operation on a resource collection of messages:

552

#

Jon Wayne Parrott

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

[diff] [blame]

553

#

554

# service Messaging {

555

# rpc GetMessage(GetMessageRequest) returns (Message) {

556

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

557

# }

558

# }

559

# message GetMessageRequest {

560

# message SubMessage {

561

# string subfield = 1;

562

# }

563

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

564

# SubMessage sub = 2; // `sub.subfield` is url-mapped

565

# }

566

# message Message {

567

# string text = 1; // content of the resource

568

# }

569

#

570

# The same http annotation can alternatively be expressed inside the

571

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

576

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

Jon Wayne Parrott

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

[diff] [blame]

577

#

578

# This definition enables an automatic, bidrectional mapping of HTTP

579

# JSON to RPC. Example:

#

# HTTP | RPC

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

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

584

#

585

# In general, not only fields but also field paths can be referenced

586

# from a path pattern. Fields mapped to the path pattern cannot be

587

# repeated and must have a primitive (non-message) type.

588

#

589

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

590

# pattern automatically become (optional) HTTP query

591

# parameters. Assume the following definition of the request message:

592

#

Jon Wayne Parrott

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

[diff] [blame]

593

#

Sai Cheemalapati

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

[diff] [blame]

594

# service Messaging {

595

# rpc GetMessage(GetMessageRequest) returns (Message) {

596

# option (google.api.http).get = "/v1/messages/{message_id}";

597

# }

598

# }

Jon Wayne Parrott

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

[diff] [blame]

599

# message GetMessageRequest {

600

# message SubMessage {

601

# string subfield = 1;

602

# }

603

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

604

# int64 revision = 2; // becomes a parameter

605

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

606

# }

607

#

Jon Wayne Parrott

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

[diff] [blame]

608

#

609

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

#

# HTTP | RPC

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

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

614

#

615

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

616

# primitive type or a repeated primitive type. Message types are not

617

# allowed. In the case of a repeated type, the parameter can be

618

# repeated in the URL, as in `...?param=A&param=B`.

619

#

620

# For HTTP method kinds which allow a request body, the `body` field

621

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

622

# message resource collection:

623

#

Jon Wayne Parrott

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

[diff] [blame]

624

#

625

# service Messaging {

626

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

627

# option (google.api.http) = {

628

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

634

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

635

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

636

# }

637

#

Jon Wayne Parrott

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

[diff] [blame]

638

#

639

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

640

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

641

# protos JSON encoding:

#

# HTTP | RPC

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

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

646

#

647

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

648

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

649

# request body. This enables the following alternative definition of

650

# the update method:

651

#

Jon Wayne Parrott

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

[diff] [blame]

652

# service Messaging {

653

# rpc UpdateMessage(Message) returns (Message) {

654

# option (google.api.http) = {

655

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

662

# string text = 2;

663

# }

664

#

Jon Wayne Parrott

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

[diff] [blame]

665

#

666

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

671

#

672

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

673

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

674

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

675

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

676

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

677

#

678

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

679

# the `additional_bindings` option. Example:

680

#

Jon Wayne Parrott

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

[diff] [blame]

681

# service Messaging {

682

# rpc GetMessage(GetMessageRequest) returns (Message) {

683

# option (google.api.http) = {

684

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

685

# additional_bindings {

686

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

687

# }

688

# };

Jon Wayne Parrott

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

[diff] [blame]

689

# }

Jon Wayne Parrott

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

[diff] [blame]

690

# }

691

# message GetMessageRequest {

692

# string message_id = 1;

693

# string user_id = 2;

694

# }

695

#

Jon Wayne Parrott

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

[diff] [blame]

696

#

697

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

703

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

704

#

705

# # Rules for HTTP mapping

706

#

707

# The rules for mapping HTTP path, query parameters, and body fields

708

# to the request message are as follows:

709

#

710

# 1. The `body` field specifies either `*` or a field path, or is

711

# omitted. If omitted, it assumes there is no HTTP body.

712

# 2. Leaf fields (recursive expansion of nested messages in the

713

# request) can be classified into three types:

714

# (a) Matched in the URL template.

715

# (b) Covered by body (if body is `*`, everything except (a) fields;

716

# else everything under the body field)

717

# (c) All other fields.

718

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

719

# 4. Any body sent with an HTTP request can contain only (b) fields.

720

#

721

# The syntax of the path template is as follows:

722

#

723

# Template = "/" Segments [ Verb ] ;

724

# Segments = Segment { "/" Segment } ;

725

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

726

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

727

# FieldPath = IDENT { "." IDENT } ;

728

# Verb = ":" LITERAL ;

729

#

730

# The syntax `*` matches a single path segment. It follows the semantics of

731

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

732

# Expansion.

733

#

734

# The syntax `**` matches zero or more path segments. It follows the semantics

735

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

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

[diff] [blame]

736

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

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

[diff] [blame]

737

#

738

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

739

#

740

# The syntax `Variable` matches the entire path as specified by its template;

741

# this nested template must not contain further variables. If a variable

742

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

743

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

744

#

745

# NOTE: the field paths in variables and in the `body` must not refer to

746

# repeated fields or map fields.

747

#

748

# Use CustomHttpPattern to specify any HTTP method that is not included in the

749

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

750

# a given URL path rule. The wild-card rule is useful for services that provide

751

# content to Web (HTML) clients.

752

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

753

# `*` for mapping all fields not captured by the path pattern to the HTTP

754

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

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

[diff] [blame]

755

# present at the top-level of request message type.

Jon Wayne Parrott

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

[diff] [blame]

756

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

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

[diff] [blame]

757

"restCollection": "A String", # Optional. The REST collection name is by default derived from the URL

758

# pattern. If specified, this field overrides the default collection name.

759

# Example:

760

#

761

# rpc AddressesAggregatedList(AddressesAggregatedListRequest)

762

# returns (AddressesAggregatedListResponse) {

763

# option (google.api.http) = {

764

# get: "/v1/projects/{project_id}/aggregated/addresses"

765

# rest_collection: "projects.addresses"

# };

# }

#

# This method has the automatically derived collection name

770

# "projects.aggregated". Because, semantically, this rpc is actually an

771

# operation on the "projects.addresses" collection, the `rest_collection`

772

# field is configured to override the derived collection name.

Jon Wayne Parrott

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

[diff] [blame]

773

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

774

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

775

# the nesting may only be one level deep).

776

# Object with schema name: HttpRule

777

],

Sai Cheemalapati

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

[diff] [blame]

778

"mediaUpload": { # Defines the Media configuration for a service in case of an upload. # Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

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

[diff] [blame]

779

# Bytestream, add instead

Jon Wayne Parrott

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

[diff] [blame]

780

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

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

[diff] [blame]

781

# configuration for Bytestream methods.

Sai Cheemalapati

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

[diff] [blame]

782

# Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

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

[diff] [blame]

783

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

784

# your configuration for Bytestream methods.

Sai Cheemalapati

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

[diff] [blame]

785

"progressNotification": True or False, # Whether to receive a notification for progress changes of media upload.

786

"startNotification": True or False, # Whether to receive a notification on the start of media upload.

787

"mimeTypes": [ # An array of mimetype patterns. Esf will only accept uploads that match one

788

# of the given patterns.

789

"A String",

790

],

791

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of an

792

# upload should be sent to the backend. These notifications will not be seen

793

# by the client and will not consume quota.

Jon Wayne Parrott

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

[diff] [blame]

794

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

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

[diff] [blame]

795

"uploadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

Sai Cheemalapati

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

[diff] [blame]

796

#

797

# Specify name of the upload service if one is used for upload.

Sai Cheemalapati

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

[diff] [blame]

798

"maxSize": "A String", # Optional maximum acceptable size for an upload.

799

# The size is specified in bytes.

800

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

Jon Wayne Parrott

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

[diff] [blame]

801

},

Thomas Coffee

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

[diff] [blame]

802

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

803

#

804

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

805

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

806

# response. Other response fields are ignored. This field is optional. When

807

# not set, the response message will be used as HTTP body of response.

808

# NOTE: the referred field must be not a repeated field and must be present

809

# at the top-level of response message type.

Sai Cheemalapati

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

[diff] [blame]

810

"restMethodName": "A String", # Optional. The rest method name is by default derived from the URL

811

# pattern. If specified, this field overrides the default method name.

812

# Example:

813

#

814

# rpc CreateResource(CreateResourceRequest)

815

# returns (CreateResourceResponse) {

816

# option (google.api.http) = {

817

# post: "/v1/resources",

818

# body: "resource",

819

# rest_method_name: "insert"

# };

# }

#

# This method has the automatically derived rest method name "create", but

824

# for backwards compatability with apiary, it is specified as insert.

825

"mediaDownload": { # Defines the Media configuration for a service in case of a download. # Use this only for Scotty Requests. Do not use this for bytestream methods.

826

# For media support, add instead [][google.bytestream.RestByteStream] as an

827

# API to your configuration.

828

# Use this only for Scotty Requests. Do not use this for media support using

829

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

830

# your configuration for Bytestream methods.

831

"useDirectDownload": True or False, # A boolean that determines if direct download from ESF should be used for

832

# download of this media.

833

"enabled": True or False, # Whether download is enabled.

834

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of a

835

# download should be sent to the backend.

836

"maxDirectDownloadSize": "A String", # Optional maximum acceptable size for direct download.

837

# The size is specified in bytes.

838

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

839

"downloadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

840

#

841

# Specify name of the download service if one is used for download.

842

},

Jon Wayne Parrott

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

[diff] [blame]

843

"put": "A String", # Used for updating a resource.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

844

"patch": "A String", # Used for updating a resource.

Thomas Coffee

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

[diff] [blame]

845

"post": "A String", # Used for creating a resource.

846

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

847

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

848

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

849

},

Jon Wayne Parrott

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

[diff] [blame]

850

"delete": "A String", # Used for deleting a resource.

851

},

852

],

Sai Cheemalapati

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

[diff] [blame]

853

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

854

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

855

# left encoded.

856

#

857

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

858

# segment matches.

Jon Wayne Parrott

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

[diff] [blame]

859

},

860

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

861

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

862

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

863

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

864

# which cannot be resolved against the associated IDL files.

865

{ # Api is a light-weight descriptor for a protocol buffer service.

Sai Cheemalapati

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

[diff] [blame]

866

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

867

# followed by the api's simple name.

Jon Wayne Parrott

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

[diff] [blame]

868

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

869

# message.

870

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

871

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

872

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

873

},

874

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

875

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

876

# redeclare all the methods from the included API, but documentation

877

# and options are inherited as follows:

878

#

879

# - If after comment and whitespace stripping, the documentation

880

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

881

# from the original method.

882

#

883

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

884

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

885

# inherited.

886

#

887

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

888

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

889

# version of the including API plus the root path if specified.

890

#

891

# Example of a simple mixin:

892

#

893

# package google.acl.v1;

894

# service AccessControl {

895

# // Get the underlying ACL object.

896

# rpc GetAcl(GetAclRequest) returns (Acl) {

897

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

# }

# }

#

# package google.storage.v2;

902

# service Storage {

903

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

904

#

905

# // Get a data record.

906

# rpc GetData(GetDataRequest) returns (Data) {

907

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

# }

# }

#

# Example of a mixin configuration:

912

#

913

# apis:

914

# - name: google.storage.v2.Storage

915

# mixins:

916

# - name: google.acl.v1.AccessControl

917

#

918

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

919

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

920

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

921

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

922

# documentation and annotations as follows:

923

#

924

# service Storage {

925

# // Get the underlying ACL object.

926

# rpc GetAcl(GetAclRequest) returns (Acl) {

927

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

# }

# ...

# }

#

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

933

#

934

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

935

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

936

#

937

# apis:

938

# - name: google.storage.v2.Storage

939

# mixins:

940

# - name: google.acl.v1.AccessControl

941

# root: acls

942

#

943

# This implies the following inherited HTTP annotation:

944

#

945

# service Storage {

946

# // Get the underlying ACL object.

947

# rpc GetAcl(GetAclRequest) returns (Acl) {

948

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

# }

# ...

# }

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

953

# are rooted.

954

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

955

},

956

],

957

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

958

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

959

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

960

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

961

# empty, the major version is derived from the package name, as

962

# outlined below. If the field is not empty, the version in the

963

# package name will be verified to be consistent with what is

964

# provided here.

965

#

966

# The versioning schema uses [semantic

967

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

968

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

969

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

970

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

971

# chosen based on the product plan.

972

#

973

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

974

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

975

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

976

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

977

# experimental, none-GA apis.

978

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

979

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

980

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

981

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

982

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

983

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

984

# `"google.api.http"`.

985

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

986

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

987

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

988

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

989

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

990

},

991

},

992

],

Sai Cheemalapati

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

[diff] [blame]

993

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

994

{ # Method represents a method of an api.

995

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

996

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

997

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

998

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

999

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

1000

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

1001

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

1002

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

1003

# enumeration, etc.

1004

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

1005

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

1006

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

1007

# `"google.api.http"`.

1008

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

1009

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

1010

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

1011

# value using the google.protobuf.Int32Value type.

1012

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

},

},

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1018

},

1019

],

1020

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

1021

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1029

# - google.foo.v1.AnotherError

1030

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

1031

#

1032

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

1033

{ # A custom error rule.

1034

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

1035

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

1036

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

1037

#

1038

# Refer to selector for syntax details.

1039

},

1040

],

1041

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

1042

"A String",

1043

],

1044

},

Sai Cheemalapati

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

[diff] [blame]

1045

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

1046

# usage.

1047

#

1048

# The quota configuration works this way:

1049

# - The service configuration defines a set of metrics.

1050

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

1051

# corresponding costs.

1052

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

1053

# quota checks at runtime.

1054

#

1055

# An example quota configuration in yaml format:

#

# quota:

#

# - name: apiWriteQpsPerProject

1060

# metric: library.googleapis.com/write_calls

1061

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

# values:

# STANDARD: 10000

#

#

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

1067

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

1068

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

1069

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1074

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

1075

# metric_costs:

1076

# library.googleapis.com/write_calls: 2

1077

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

1078

# metric_costs:

1079

# library.googleapis.com/write_calls: 1

1080

#

1081

# Corresponding Metric definition:

1082

#

1083

# metrics:

1084

# - name: library.googleapis.com/read_calls

1085

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1090

# display_name: Write requests

1091

# metric_kind: DELTA

1092

# value_type: INT64

1093

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

1094

# or more metrics.

1095

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

1096

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

1097

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

1098

# cost applied to each metric.

1099

#

1100

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

1101

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

1102

# The value must not be negative.

1103

"a_key": "A String",

1104

},

1105

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

1106

#

1107

# Refer to selector for syntax details.

1108

},

1109

],

1110

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

1111

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

1112

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

1113

# type combination defined within a `QuotaGroup`.

1114

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

1115

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

1116

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

1117

# display name generated from the configuration.

1118

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

1119

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

1120

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

1121

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

1122

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

1123

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

1124

#

1125

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

1126

# are provisioning quota to selected consumers and blocking others.

1127

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

1128

# negative values are allowed.

1129

#

1130

# Used by group-based quotas only.

1131

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

1132

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

1133

# defined within the service config.

1134

#

1135

# Used by metric-based quotas only.

1136

"values": { # Tiered limit values, currently only STANDARD is supported.

1137

"a_key": "A String",

1138

},

1139

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

1140

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

1141

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

1142

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

1143

#

1144

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

1145

# indicating unlimited maximum quota.

1146

#

1147

# Used by group-based quotas only.

1148

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

1149

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

1150

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

1151

# the future. "0" indicates indefinite duration.

1152

#

1153

# Used by group-based quotas only.

1154

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

1155

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

1156

# billed amount when billing is enabled.

1157

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

1158

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

1159

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

1160

#

1161

# Used by group-based quotas only.

1162

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

1163

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

1164

# backend system.

1165

#

1166

# The [Google Service Control](https://cloud.google.com/service-control)

1167

# supports the following unit components:

1168

# * One of the time intevals:

1169

# * "/min" for quota every minute.

1170

# * "/d" for quota every 24 hours, starting 00:00 US Pacific Time.

1171

# * Otherwise the quota won't be reset by time, such as storage limit.

1172

# * One and only one of the granted containers:

1173

# * "/{project}" quota for a project

1174

#

1175

# Here are some examples:

1176

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

1177

#

1178

# Note: the order of unit components is insignificant.

1179

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

1180

#

1181

# Used by metric-based quotas only.

1182

"name": "A String", # Name of the quota limit. The name is used to refer to the limit when

1183

# overriding the default limit on per-consumer basis.

1184

#

1185

# For metric-based quota limits, the name must be provided, and it must be

1186

# unique within the service. The name can only include alphanumeric

1187

# characters as well as '-'.

1188

#

1189

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

1190

#

1191

# The name of a limit is used as a unique identifier for this limit.

1192

# Therefore, once a limit has been put into use, its name should be

1193

# immutable. You can use the display_name field to provide a user-friendly

1194

# name for the limit. The display name can be evolved over time without

1195

# affecting the identity of the limit.

1196

},

1197

],

1198

},

Jon Wayne Parrott

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

[diff] [blame]

1199

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

1200

# elements. Restrictions are specified using visibility labels

1201

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

1202

#

1203

# Users and projects can have access to more than one visibility label. The

1204

# effective visibility for multiple labels is the union of each label's

1205

# elements, plus any unrestricted elements.

1206

#

1207

# If an element and its parents have no restrictions, visibility is

1208

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1215

# restriction: TRUSTED_TESTER

1216

# - selector: google.calendar.Calendar.Delegate

1217

# restriction: GOOGLE_INTERNAL

1218

#

1219

# Here, all methods are publicly visible except for the restricted methods

1220

# EnhancedSearch and Delegate.

1221

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

1222

#

1223

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

1224

{ # A visibility rule provides visibility configuration for an individual API

1225

# element.

Sai Cheemalapati

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

[diff] [blame]

1226

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

1227

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

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

[diff] [blame]

1228

#

1229

# If a rule has multiple labels, removing one of the labels but not all of

1230

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1237

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1238

#

1239

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1240

# rely on this method and only had access to it through GOOGLE_INTERNAL.

1241

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

1242

#

1243

# Refer to selector for syntax details.

},

],

},

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

Jon Wayne Parrott

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

[diff] [blame]

1248

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

1249

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

1250

# existing data unusable.

Jon Wayne Parrott

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

[diff] [blame]

1251

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

1252

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

Thomas Coffee

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

[diff] [blame]

1253

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

1254

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

1255

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

Jon Wayne Parrott

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

[diff] [blame]

1256

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

1257

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

Jon Wayne Parrott

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

[diff] [blame]

1258

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

1259

# instance of this metric type. For example, the

1260

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

1261

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

1262

# you can look at latencies for successful responses or just

1263

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1264

{ # A description of a label.

1265

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

1266

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

1267

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

1268

},

1269

],

Jon Wayne Parrott

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

[diff] [blame]

1270

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

Sai Cheemalapati

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

[diff] [blame]

1271

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

Jon Wayne Parrott

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

[diff] [blame]

1272

# `custom.googleapis.com`. Metric types should use a natural hierarchical

1273

# grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1274

#

Jon Wayne Parrott

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

[diff] [blame]

1275

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

1276

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

Jon Wayne Parrott

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

[diff] [blame]

1277

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

1278

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

1279

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

1280

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

1281

#

1282

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

1297

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

1298

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

1299

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

1300

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

1301

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

1302

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

1303

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

1304

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

1305

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

1306

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

1307

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

1308

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

1309

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

1310

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

1311

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

1312

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

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

1317

#

1318

# The grammar also includes these connectors:

1319

#

1320

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

1321

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

1322

#

1323

# The grammar for a unit is as follows:

1324

#

1325

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

1326

#

1327

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1337

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

1338

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

1339

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

1340

# containing '{' or '}'.

Thomas Coffee

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

[diff] [blame]

1341

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

1342

# implementation, the name typically includes: (1) the parent resource name

1343

# that defines the scope of the metric type or of its data; and (2) the

1344

# metric's URL-encoded type, which also appears in the `type` field of this

1345

# descriptor. For example, following is the resource name of a custom

1346

# metric within the GCP project `my-project-id`:

1347

#

1348

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

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

[diff] [blame]

1349

},

1350

],

1351

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

1352

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

1353

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

1354

# should be listed here by name. Example:

1355

#

1356

# enums:

1357

# - name: google.someapi.v1.SomeEnum

1358

{ # Enum type definition.

1359

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

1360

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

1361

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

1362

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

1363

},

Sai Cheemalapati

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

[diff] [blame]

1364

"enumvalue": [ # Enum value definitions.

1365

{ # Enum value definition.

1366

"options": [ # Protocol buffer options.

1367

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

1368

# enumeration, etc.

1369

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

1370

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

1371

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

1372

# `"google.api.http"`.

1373

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

1374

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

1375

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

1376

# value using the google.protobuf.Int32Value type.

1377

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

},

},

],

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

1382

"number": 42, # Enum value number.

1383

},

1384

],

Thomas Coffee

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

[diff] [blame]

1385

"options": [ # Protocol buffer options.

1386

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

1387

# enumeration, etc.

1388

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

1389

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

1390

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

1391

# `"google.api.http"`.

1392

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

1393

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

1394

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

1395

# value using the google.protobuf.Int32Value type.

1396

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

1401

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

Jon Wayne Parrott

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

[diff] [blame]

1402

},

1403

],

1404

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

1405

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

1406

# automatically included. Messages which are not referenced but

1407

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

1408

# should be listed here by name. Example:

1409

#

1410

# types:

1411

# - name: google.protobuf.Int32

1412

{ # A protocol buffer message type.

1413

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

1414

"A String",

1415

],

1416

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

Jon Wayne Parrott

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

[diff] [blame]

1417

"fields": [ # The list of fields.

1418

{ # A single field of a message type.

1419

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

1420

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

1421

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

1422

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

1423

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

1424

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

1425

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

1426

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

1427

"number": 42, # The field number.

1428

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

1429

"options": [ # The protocol buffer options.

1430

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

1431

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1432

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

1433

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

1434

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

1435

# `"google.api.http"`.

1436

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

1437

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

1438

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

1439

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1440

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

},

},

],

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

1445

},

1446

],

Sai Cheemalapati

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

[diff] [blame]

1447

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

1448

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

1449

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

1450

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

1451

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

1452

},

Jon Wayne Parrott

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

[diff] [blame]

1453

"options": [ # The protocol buffer options.

1454

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

1455

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1456

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

1457

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

1458

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

1459

# `"google.api.http"`.

1460

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

1461

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

1462

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

1463

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1464

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1470

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

Jon Wayne Parrott

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

[diff] [blame]

1471

#

1472

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

Sai Cheemalapati

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

[diff] [blame]

1473

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

1474

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

1475

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

Jon Wayne Parrott

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

[diff] [blame]

1476

#

1477

# monitored_resources:

1478

# - type: library.googleapis.com/branch

1479

# labels:

1480

# - key: /city

1481

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

1482

# - key: /name

1483

# description: The name of the branch.

1484

# logs:

Sai Cheemalapati

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

[diff] [blame]

1485

# - name: activity_history

Jon Wayne Parrott

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

[diff] [blame]

1486

# labels:

1487

# - key: /customer_id

Sai Cheemalapati

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

[diff] [blame]

1488

# - name: purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1489

# logging:

1490

# producer_destinations:

1491

# - monitored_resource: library.googleapis.com/branch

1492

# logs:

Sai Cheemalapati

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

[diff] [blame]

1493

# - activity_history

1494

# - purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1495

# consumer_destinations:

1496

# - monitored_resource: library.googleapis.com/branch

1497

# logs:

Sai Cheemalapati

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

[diff] [blame]

1498

# - activity_history

Jon Wayne Parrott

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

[diff] [blame]

1499

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

1500

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

1501

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

1502

# one producer destination.

1503

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

1504

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1505

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

1506

# Service.monitored_resources section.

1507

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

1508

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

1509

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

1510

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

1516

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

1517

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

1518

# one consumer destination.

1519

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

1520

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1521

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

1522

# Service.monitored_resources section.

1523

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

1524

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

1525

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

1526

# the service name followed by "/".

Jon Wayne Parrott

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

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

1533

# e.g. `calendar.googleapis.com`.

1534

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

1535

#

1536

# Example:

1537

# <pre><code>documentation:

1538

# summary: >

1539

# The Google Calendar API gives access

1540

# to most calendar features.

1541

# pages:

1542

# - name: Overview

1543

# content: (== include google/foo/overview.md ==)

1544

# - name: Tutorial

1545

# content: (== include google/foo/tutorial.md ==)

1546

# subpages;

1547

# - name: Java

1548

# content: (== include google/foo/tutorial_java.md ==)

1549

# rules:

1550

# - selector: google.calendar.Calendar.Get

1551

# description: >

1552

# ...

1553

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1558

# standard markdown features, definition lists, tables and fenced

1559

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

1560

# interpreted relative to the section nesting of the context where

1561

# a documentation fragment is embedded.

1562

#

1563

# Documentation from the IDL is merged with documentation defined

1564

# via the config at normalization time, where documentation provided

1565

# by config rules overrides IDL provided.

1566

#

1567

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

1568

# in documentation text.

1569

#

1570

# In order to reference a proto element, the following

1571

# notation can be used:

1572

# <pre><code>[fully.qualified.proto.name][]</code></pre>

1573

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

1574

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

1575

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

1576

# <pre><code>(-- internal comment --)</code></pre>

1577

# Comments can be made conditional using a visibility label. The below

1578

# text will be only rendered if the `BETA` label is available:

1579

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

1580

# A few directives are available in documentation. Note that

1581

# directives must appear on a single line to be properly

1582

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

1583

# an external source:

1584

# <pre><code>(== include path/to/file ==)</code></pre>

1585

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

1586

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

1587

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

1588

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

1589

# The directive `suppress_warning` does not directly affect documentation

1590

# and is documented together with service config validation.

1591

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

1592

#

1593

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

1594

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

1595

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

1596

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

1597

# element is marked as `deprecated`.

1598

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

1599

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

1600

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

1601

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

1602

# specify a default for all applicable elements, the whole pattern "*"

1603

# is used.

1604

},

1605

],

Sai Cheemalapati

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

[diff] [blame]

1606

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

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1607

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

1608

# <pre><code>documentation:

1609

# summary: ...

1610

# overview: (== include overview.md ==)

1611

# </code></pre>

1612

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

1613

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

1618

# </code></pre>

1619

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

Jon Wayne Parrott

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

[diff] [blame]

1620

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

1621

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

1622

# nested documentation set structure.

1623

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

1624

# to include content from a Markdown file.

1625

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

1626

# honored in the generated docset.

1627

# Object with schema name: Page

1628

],

1629

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

1630

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

1631

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

1632

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

1633

# documentation. For example:

1634

# <pre><code>pages:

1635

# - name: Tutorial

1636

# content: (== include tutorial.md ==)

1637

# subpages:

1638

# - name: Java

1639

# content: (== include tutorial_java.md ==)

1640

# </code></pre>

1641

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

1642

# `Java`.

1643

},

1644

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1645

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

1646

# plain text.

Sai Cheemalapati

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

[diff] [blame]

1647

},

1648

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

1649

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

1650

{

1651

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

1652

},

1653

],

Jon Wayne Parrott

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

[diff] [blame]

1654

},

1655

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

1656

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

1657

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

1658

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

1659

# to define system APIs in ESF.

1660

{ # A protocol buffer message type.

1661

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

1662

"A String",

1663

],

1664

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

Jon Wayne Parrott

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

[diff] [blame]

1665

"fields": [ # The list of fields.

1666

{ # A single field of a message type.

1667

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

1668

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

1669

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

1670

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

1671

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

1672

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

1673

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

1674

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

1675

"number": 42, # The field number.

1676

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

1677

"options": [ # The protocol buffer options.

1678

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

1679

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1680

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

1681

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

1682

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

1683

# `"google.api.http"`.

1684

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

1685

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

1686

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

1687

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1688

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

},

},

],

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

1693

},

1694

],

Sai Cheemalapati

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

[diff] [blame]

1695

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

1696

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

1697

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

1698

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

1699

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

1700

},

Jon Wayne Parrott

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

[diff] [blame]

1701

"options": [ # The protocol buffer options.

1702

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

1703

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1704

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

1705

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

1706

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

1707

# `"google.api.http"`.

1708

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

1709

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

1710

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

1711

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1712

"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

1727

# - google.rpc.context.OriginContext

1728

#

1729

# The above specifies that all methods in the API request

1730

# `google.rpc.context.ProjectContext` and

1731

# `google.rpc.context.OriginContext`.

1732

#

1733

# Available context types are defined in package

1734

# `google.rpc.context`.

1735

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

1736

#

1737

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

1738

{ # A context rule provides information about the context for an individual API

1739

# element.

1740

"provided": [ # A list of full type names of provided contexts.

1741

"A String",

1742

],

Thomas Coffee

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

[diff] [blame]

1743

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

1744

#

1745

# Refer to selector for syntax details.

Sai Cheemalapati

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

[diff] [blame]

1746

"requested": [ # A list of full type names of requested contexts.

1747

"A String",

1748

],

Jon Wayne Parrott

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

[diff] [blame]

1749

},

1750

],

1751

},

Sai Cheemalapati

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

[diff] [blame]

1752

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

1753

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

1754

# defined APIs.

1755

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

1756

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

1757

# same service configuration, such as quota configuration and monitoring

1758

# configuration.

1759

#

1760

# Example service configuration:

1761

#

1762

# name: library-example.googleapis.com

1763

# endpoints:

1764

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

1765

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

1766

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

1767

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

1768

# # allowed to proceed.

1769

# - name: library-example.googleapis.com

Sai Cheemalapati

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

[diff] [blame]

1770

# allow_cors: true

Sai Cheemalapati

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

[diff] [blame]

1771

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

1772

# handle requests to this [API Endpoint](https://cloud.google.com/apis/design/glossary).

1773

# It should be either a valid IPv4 address or a fully-qualified domain name.

1774

# For example, "8.8.8.8" or "myservice.appspot.com".

1775

"apis": [ # The list of APIs served by this endpoint.

1776

#

1777

# If no APIs are specified this translates to "all APIs" exported by the

1778

# service, as defined in the top-level service configuration.

1779

"A String",

1780

],

Sai Cheemalapati

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

[diff] [blame]

1781

"allowCors": True or False, # Allowing

1782

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

1783

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

1784

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

1785

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

1786

# allowed to proceed.

Sai Cheemalapati

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

[diff] [blame]

1787

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

Sai Cheemalapati

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

[diff] [blame]

1788

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

1789

"A String",

1790

],

Thomas Coffee

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

[diff] [blame]

1791

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

1792

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

1793

# alias.

1794

#

1795

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

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

[diff] [blame]

"A String",

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1800

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

1801

# only be used by whitelisted users.

1802

"authorization": { # Configuration of authorization. # Authorization configuration.

1803

#

1804

# This section determines the authorization provider, if unspecified, then no

1805

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

1812

"provider": "A String", # The name of the authorization provider, such as

1813

# firebaserules.googleapis.com.

1814

},

1815

},

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.

Thomas Coffee

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

[diff] [blame]

1866

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

1867

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

1868

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

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

[diff] [blame]

1869

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

1870

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

1871

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

1872

{ # A description of a label.

1873

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

1874

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

1875

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

1876

},

1877

],

Thomas Coffee

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

[diff] [blame]

1878

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

1879

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

1880

# without any article or other determiners. For example,

1881

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

1882

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

1883

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

1884

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

1885

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

1886

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

1887

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

Sai Cheemalapati

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

[diff] [blame]

1888

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

1889

# be used in documentation.

Jon Wayne Parrott

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

[diff] [blame]

1890

},

1891

],

1892

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

1893

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

1894

#

1895

# - name: library.googleapis.com/activity_history

1896

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

1897

# display_name: Activity

1898

# labels:

1899

# - key: /customer_id

1900

# description: Identifier of a library customer

1901

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

1902

# Runtime requests that contain labels not specified here are

1903

# considered invalid.

1904

{ # A description of a label.

1905

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

1906

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

1907

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

1908

},

1909

],

1910

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

1911

# the user interface and should be concise.

Jon Wayne Parrott

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

[diff] [blame]

1912

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

1913

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

1914

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

1915

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

Thomas Coffee

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

[diff] [blame]

1916

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

1917

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

1918

},

1919

],

Thomas Coffee

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

[diff] [blame]

1920

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

1921

#

1922

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

1923

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

1924

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

1925

# change the names of the system parameters.

1926

"rules": [ # Define system parameters.

1927

#

1928

# The parameters defined here will override the default parameters

1929

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

1930

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

1931

# and names is implementation-dependent.

1932

#

1933

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1941

#

1942

#

1943

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1948

# parameters:

1949

# - name: api_key

1950

# http_header: Api-Key1

1951

# - name: api_key

1952

# http_header: Api-Key2

1953

#

1954

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

1955

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

1956

# methods.

1957

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

1958

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

1959

# names are used the behavior is implementation-dependent.

1960

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

1961

# parameter-dependent.

1962

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

1963

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

1964

# is implementation-dependent.

1965

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

1966

# sensitive.

1967

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

1968

# insensitive.

1969

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

1970

},

1971

],

1972

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

1973

# methods in all APIs.

1974

#

1975

# Refer to selector for syntax details.

1976

},

1977

],

1978

},

Sai Cheemalapati

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

[diff] [blame]

1979

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

1980

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

1981

# generate one instead.

Jon Wayne Parrott

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

[diff] [blame]

1982

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

1983

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

1984

#

1985

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

1986

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

1987

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

1988

#

1989

# Refer to selector for syntax details.

Sai Cheemalapati

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

[diff] [blame]

1990

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

1991

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1992

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

1993

# default depends on the deployment context.

1994

"address": "A String", # The address of the API backend.

1995

},

1996

],

1997

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1998

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1999

#

2000

# The example below shows how to configure monitored resources and metrics

2001

# for monitoring. In the example, a monitored resource and two metrics are

2002

# defined. The `library.googleapis.com/book/returned_count` metric is sent

2003

# to both producer and consumer projects, whereas the

2004

# `library.googleapis.com/book/overdue_count` metric is only sent to the

2005

# consumer project.

2006

#

2007

# monitored_resources:

2008

# - type: library.googleapis.com/branch

2009

# labels:

2010

# - key: /city

2011

# description: The city where the library branch is located in.

2012

# - key: /name

2013

# description: The name of the branch.

2014

# metrics:

2015

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

2020

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

2025

# monitoring:

2026

# producer_destinations:

2027

# - monitored_resource: library.googleapis.com/branch

2028

# metrics:

2029

# - library.googleapis.com/book/returned_count

2030

# consumer_destinations:

2031

# - monitored_resource: library.googleapis.com/branch

2032

# metrics:

2033

# - library.googleapis.com/book/returned_count

2034

# - library.googleapis.com/book/overdue_count

2035

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

2036

# There can be multiple producer destinations, each one must have a

2037

# different monitored resource type. A metric can be used in at most

2038

# one producer destination.

2039

{ # Configuration of a specific monitoring destination (the producer project

2040

# or the consumer project).

2041

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2042

# Service.monitored_resources section.

2043

"metrics": [ # Names of the metrics to report to this monitoring destination.

2044

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

2050

# There can be multiple consumer destinations, each one must have a

2051

# different monitored resource type. A metric can be used in at most

2052

# one consumer destination.

2053

{ # Configuration of a specific monitoring destination (the producer project

2054

# or the consumer project).

2055

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2056

# Service.monitored_resources section.

2057

"metrics": [ # Names of the metrics to report to this monitoring destination.

2058

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2064

"title": "A String", # The product title associated with this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2065

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

2066

#

2067

# Example for an API targeted for external use:

2068

#

2069

# name: calendar.googleapis.com

2070

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2071

# providers:

2072

# - id: google_calendar_auth

2073

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

2074

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2075

# rules:

2076

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2077

# requirements:

2078

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2079

"rules": [ # A list of authentication rules that apply to individual API methods.

2080

#

2081

# **NOTE:** All service configuration rules follow "last one wins" order.

2082

{ # Authentication rules for the service.

2083

#

2084

# By default, if a method has any authentication requirements, every request

2085

# must include a valid credential matching one of the requirements.

2086

# It's an error to include more than one kind of credential in a single

2087

# request.

2088

#

2089

# If a method doesn't have any auth requirements, request credentials will be

2090

# ignored.

2091

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

2092

# there are scopes defined for "Read-only access to Google Calendar" and

2093

# "Access to Cloud Platform". Users can consent to a scope for an application,

2094

# giving it permission to access that data on their behalf.

2095

#

2096

# OAuth scope specifications should be fairly coarse grained; a user will need

2097

# to see and understand the text description of what your scope means.

2098

#

2099

# In most cases: use one or at most two OAuth scopes for an entire family of

2100

# products. If your product has multiple APIs, you should probably be sharing

2101

# the OAuth scope across all of those APIs.

2102

#

2103

# When you need finer grained OAuth consent screens: talk with your product

2104

# management about how developers will use them in practice.

2105

#

2106

# Please note that even though each of the canonical scopes is enough for a

2107

# request to be accepted and passed to the backend, a request can still fail

2108

# due to the backend requiring additional scopes or permissions.

2109

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

2110

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

2115

# https://www.googleapis.com/auth/calendar.read

2116

},

2117

"requirements": [ # Requirements for additional authentication providers.

2118

{ # User-defined authentication requirements, including support for

2119

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

2120

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2125

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

2126

# implemented and accepted in all the runtime components.

2127

#

2128

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2129

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2130

# that are allowed to access. A JWT containing any of these audiences will

2131

# be accepted. When this setting is absent, only JWTs with audience

2132

# "https://Service_name/API_name"

2133

# will be accepted. For example, if no audiences are in the setting,

2134

# LibraryService API will only accept JWTs with the following audience

2135

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2140

# bookstore_web.apps.googleusercontent.com

2141

},

2142

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2143

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

2144

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

2145

#

2146

# For requests without credentials, if the service control environment is

2147

# specified, each incoming request **must** be associated with a service

2148

# consumer. This can be done by passing an API key that belongs to a consumer

2149

# project.

2150

"customAuth": { # Configuration for a custom authentication provider. # Configuration for custom authentication.

2151

"provider": "A String", # A configuration string containing connection information for the

2152

# authentication provider, typically formatted as a SmartService string

2153

# (go/smartservice).

2154

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2155

"selector": "A String", # Selects the methods to which this rule applies.

2156

#

2157

# Refer to selector for syntax details.

2158

},

2159

],

2160

"providers": [ # Defines a set of authentication providers that a service supports.

2161

{ # Configuration for an anthentication provider, including support for

2162

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2163

"audiences": "A String", # The list of JWT

2164

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

2165

# that are allowed to access. A JWT containing any of these audiences will

2166

# be accepted. When this setting is absent, only JWTs with audience

2167

# "https://Service_name/API_name"

2168

# will be accepted. For example, if no audiences are in the setting,

2169

# LibraryService API will only accept JWTs with the following audience

2170

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

2175

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2176

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

2177

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

2178

# Optional if the key set document:

2179

# - can be retrieved from

2180

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

2181

# of the issuer.

2182

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

2183

#

2184

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2185

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

2186

# `AuthRequirement.provider_id`.

2187

#

2188

# Example: "bookstore_auth".

2189

"issuer": "A String", # Identifies the principal that issued the JWT. See

2190

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

2191

# Usually a URL or an email address.

2192

#

2193

# Example: https://securetoken.google.com

2194

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

2199

"rules": [ # A list of usage rules that apply to individual API methods.

2200

#

2201

# **NOTE:** All service configuration rules follow "last one wins" order.

2202

{ # Usage configuration rules for the service.

2203

#

2204

# NOTE: Under development.

2205

#

2206

#

2207

# Use this rule to configure unregistered calls for the service. Unregistered

2208

# calls are calls that do not contain consumer project identity.

2209

# (Example: calls that do not contain an API key).

2210

# By default, API methods do not allow unregistered calls, and each method call

2211

# must be identified by a consumer project identity. Use this rule to

2212

# allow/disallow unregistered calls.

2213

#

2214

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

2220

#

2221

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

2226

# allow_unregistered_calls: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2227

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2228

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

2229

# methods in all APIs.

2230

#

2231

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2232

},

2233

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2234

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

2235

# service producer.

2236

#

2237

# Google Service Management currently only supports

2238

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2239

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2240

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2241

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2242

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

2243

# service. Each requirement is of the form <service.name>/<requirement-id>;

2244

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

2249

# influence interpretation of the configuration, for example, to

2250

# determine defaults. This is documented together with applicable

2251

# options. The current default for the config version itself is `3`.

2252

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

2253

# Members of this project can manage the service configuration,

2254

# manage consumption of the service, etc.

2255

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

2256

# HttpRule, each specifying the mapping of an RPC method

2257

# to one or more HTTP REST API methods.

2258

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2259

#

2260

# **NOTE:** All service configuration rules follow "last one wins" order.

2261

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

2262

# REST APIs. The mapping determines what portions of the request

2263

# message are populated from the path, query parameters, or body of

2264

# the HTTP request. The mapping is typically specified as an

2265

# `google.api.http` annotation, see "google/api/annotations.proto"

2266

# for details.

2267

#

2268

# The mapping consists of a field specifying the path template and

2269

# method kind. The path template can refer to fields in the request

2270

# message, as in the example below which describes a REST GET

2271

# operation on a resource collection of messages:

2272

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2273

#

2274

# service Messaging {

2275

# rpc GetMessage(GetMessageRequest) returns (Message) {

2276

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

2277

# }

2278

# }

2279

# message GetMessageRequest {

2280

# message SubMessage {

2281

# string subfield = 1;

2282

# }

2283

# string message_id = 1; // mapped to the URL

2284

# SubMessage sub = 2; // `sub.subfield` is url-mapped

2285

# }

2286

# message Message {

2287

# string text = 1; // content of the resource

2288

# }

2289

#

2290

# The same http annotation can alternatively be expressed inside the

2291

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

2296

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2297

#

2298

# This definition enables an automatic, bidrectional mapping of HTTP

2299

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

2304

#

2305

# In general, not only fields but also field paths can be referenced

2306

# from a path pattern. Fields mapped to the path pattern cannot be

2307

# repeated and must have a primitive (non-message) type.

2308

#

2309

# Any fields in the request message which are not bound by the path

2310

# pattern automatically become (optional) HTTP query

2311

# parameters. Assume the following definition of the request message:

2312

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2313

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2314

# service Messaging {

2315

# rpc GetMessage(GetMessageRequest) returns (Message) {

2316

# option (google.api.http).get = "/v1/messages/{message_id}";

2317

# }

2318

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2319

# message GetMessageRequest {

2320

# message SubMessage {

2321

# string subfield = 1;

2322

# }

2323

# string message_id = 1; // mapped to the URL

2324

# int64 revision = 2; // becomes a parameter

2325

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

2326

# }

2327

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2328

#

2329

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

2334

#

2335

# Note that fields which are mapped to HTTP parameters must have a

2336

# primitive type or a repeated primitive type. Message types are not

2337

# allowed. In the case of a repeated type, the parameter can be

2338

# repeated in the URL, as in `...?param=A&param=B`.

2339

#

2340

# For HTTP method kinds which allow a request body, the `body` field

2341

# specifies the mapping. Consider a REST update method on the

2342

# message resource collection:

2343

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2344

#

2345

# service Messaging {

2346

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2347

# option (google.api.http) = {

2348

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2354

# string message_id = 1; // mapped to the URL

2355

# Message message = 2; // mapped to the body

2356

# }

2357

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2358

#

2359

# The following HTTP JSON to RPC mapping is enabled, where the

2360

# representation of the JSON in the request body is determined by

2361

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

2366

#

2367

# The special name `*` can be used in the body mapping to define that

2368

# every field not bound by the path template should be mapped to the

2369

# request body. This enables the following alternative definition of

2370

# the update method:

2371

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2372

# service Messaging {

2373

# rpc UpdateMessage(Message) returns (Message) {

2374

# option (google.api.http) = {

2375

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

2382

# string text = 2;

2383

# }

2384

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2385

#

2386

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

2391

#

2392

# Note that when using `*` in the body mapping, it is not possible to

2393

# have HTTP parameters, as all fields not bound by the path end in

2394

# the body. This makes this option more rarely used in practice of

2395

# defining REST APIs. The common usage of `*` is in custom methods

2396

# which don't use the URL at all for transferring data.

2397

#

2398

# It is possible to define multiple HTTP methods for one RPC by using

2399

# the `additional_bindings` option. Example:

2400

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2401

# service Messaging {

2402

# rpc GetMessage(GetMessageRequest) returns (Message) {

2403

# option (google.api.http) = {

2404

# get: "/v1/messages/{message_id}"

2405

# additional_bindings {

2406

# get: "/v1/users/{user_id}/messages/{message_id}"

2407

# }

2408

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2409

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2410

# }

2411

# message GetMessageRequest {

2412

# string message_id = 1;

2413

# string user_id = 2;

2414

# }

2415

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2416

#

2417

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

2423

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

2424

#

2425

# # Rules for HTTP mapping

2426

#

2427

# The rules for mapping HTTP path, query parameters, and body fields

2428

# to the request message are as follows:

2429

#

2430

# 1. The `body` field specifies either `*` or a field path, or is

2431

# omitted. If omitted, it assumes there is no HTTP body.

2432

# 2. Leaf fields (recursive expansion of nested messages in the

2433

# request) can be classified into three types:

2434

# (a) Matched in the URL template.

2435

# (b) Covered by body (if body is `*`, everything except (a) fields;

2436

# else everything under the body field)

2437

# (c) All other fields.

2438

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

2439

# 4. Any body sent with an HTTP request can contain only (b) fields.

2440

#

2441

# The syntax of the path template is as follows:

2442

#

2443

# Template = "/" Segments [ Verb ] ;

2444

# Segments = Segment { "/" Segment } ;

2445

# Segment = "*" | "**" | LITERAL | Variable ;

2446

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2447

# FieldPath = IDENT { "." IDENT } ;

2448

# Verb = ":" LITERAL ;

2449

#

2450

# The syntax `*` matches a single path segment. It follows the semantics of

2451

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2452

# Expansion.

2453

#

2454

# The syntax `**` matches zero or more path segments. It follows the semantics

2455

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2456

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2457

#

2458

# The syntax `LITERAL` matches literal text in the URL path.

2459

#

2460

# The syntax `Variable` matches the entire path as specified by its template;

2461

# this nested template must not contain further variables. If a variable

2462

# matches a single path segment, its template may be omitted, e.g. `{var}`

2463

# is equivalent to `{var=*}`.

2464

#

2465

# NOTE: the field paths in variables and in the `body` must not refer to

2466

# repeated fields or map fields.

2467

#

2468

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2469

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2470

# a given URL path rule. The wild-card rule is useful for services that provide

2471

# content to Web (HTML) clients.

2472

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2473

# `*` for mapping all fields not captured by the path pattern to the HTTP

2474

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2475

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2476

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2477

"restCollection": "A String", # Optional. The REST collection name is by default derived from the URL

2478

# pattern. If specified, this field overrides the default collection name.

2479

# Example:

2480

#

2481

# rpc AddressesAggregatedList(AddressesAggregatedListRequest)

2482

# returns (AddressesAggregatedListResponse) {

2483

# option (google.api.http) = {

2484

# get: "/v1/projects/{project_id}/aggregated/addresses"

2485

# rest_collection: "projects.addresses"

# };

# }

#

# This method has the automatically derived collection name

2490

# "projects.aggregated". Because, semantically, this rpc is actually an

2491

# operation on the "projects.addresses" collection, the `rest_collection`

2492

# field is configured to override the derived collection name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2493

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2494

# not contain an `additional_bindings` field themselves (that is,

2495

# the nesting may only be one level deep).

2496

# Object with schema name: HttpRule

2497

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2498

"mediaUpload": { # Defines the Media configuration for a service in case of an upload. # Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2499

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2500

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2501

# configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2502

# Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2503

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

2504

# your configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2505

"progressNotification": True or False, # Whether to receive a notification for progress changes of media upload.

2506

"startNotification": True or False, # Whether to receive a notification on the start of media upload.

2507

"mimeTypes": [ # An array of mimetype patterns. Esf will only accept uploads that match one

2508

# of the given patterns.

2509

"A String",

2510

],

2511

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of an

2512

# upload should be sent to the backend. These notifications will not be seen

2513

# by the client and will not consume quota.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2514

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2515

"uploadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2516

#

2517

# Specify name of the upload service if one is used for upload.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2518

"maxSize": "A String", # Optional maximum acceptable size for an upload.

2519

# The size is specified in bytes.

2520

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2521

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2522

"selector": "A String", # Selects methods to which this rule applies.

2523

#

2524

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2525

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2526

# response. Other response fields are ignored. This field is optional. When

2527

# not set, the response message will be used as HTTP body of response.

2528

# NOTE: the referred field must be not a repeated field and must be present

2529

# at the top-level of response message type.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2530

"restMethodName": "A String", # Optional. The rest method name is by default derived from the URL

2531

# pattern. If specified, this field overrides the default method name.

2532

# Example:

2533

#

2534

# rpc CreateResource(CreateResourceRequest)

2535

# returns (CreateResourceResponse) {

2536

# option (google.api.http) = {

2537

# post: "/v1/resources",

2538

# body: "resource",

2539

# rest_method_name: "insert"

# };

# }

#

# This method has the automatically derived rest method name "create", but

2544

# for backwards compatability with apiary, it is specified as insert.

2545

"mediaDownload": { # Defines the Media configuration for a service in case of a download. # Use this only for Scotty Requests. Do not use this for bytestream methods.

2546

# For media support, add instead [][google.bytestream.RestByteStream] as an

2547

# API to your configuration.

2548

# Use this only for Scotty Requests. Do not use this for media support using

2549

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

2550

# your configuration for Bytestream methods.

2551

"useDirectDownload": True or False, # A boolean that determines if direct download from ESF should be used for

2552

# download of this media.

2553

"enabled": True or False, # Whether download is enabled.

2554

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of a

2555

# download should be sent to the backend.

2556

"maxDirectDownloadSize": "A String", # Optional maximum acceptable size for direct download.

2557

# The size is specified in bytes.

2558

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

2559

"downloadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

2560

#

2561

# Specify name of the download service if one is used for download.

2562

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2563

"put": "A String", # Used for updating a resource.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

2564

"patch": "A String", # Used for updating a resource.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2565

"post": "A String", # Used for creating a resource.

2566

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2567

"path": "A String", # The path matched by this custom verb.

2568

"kind": "A String", # The name of this custom HTTP verb.

2569

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2570

"delete": "A String", # Used for deleting a resource.

2571

},

2572

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2573

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parmeters will be fully URI-decoded except in

2574

# cases of single segment matches in reserved expansion, where "%2F" will be

2575

# left encoded.

2576

#

2577

# The default behavior is to not decode RFC 6570 reserved characters in multi

2578

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2579

},

2580

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2581

# of the google.protobuf.Api needs to be provided by the configuration

2582

# author, as the remaining fields will be derived from the IDL during the

2583

# normalization process. It is an error to specify an API interface here

2584

# which cannot be resolved against the associated IDL files.

2585

{ # Api is a light-weight descriptor for a protocol buffer service.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2586

"name": "A String", # The fully qualified name of this api, including package name

2587

# followed by the api's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2588

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2589

# message.

2590

# protobuf element, like the file in which it is defined.

2591

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2592

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2593

},

2594

"mixins": [ # Included APIs. See Mixin.

2595

{ # Declares an API to be included in this API. The including API must

2596

# redeclare all the methods from the included API, but documentation

2597

# and options are inherited as follows:

2598

#

2599

# - If after comment and whitespace stripping, the documentation

2600

# string of the redeclared method is empty, it will be inherited

2601

# from the original method.

2602

#

2603

# - Each annotation belonging to the service config (http,

2604

# visibility) which is not set in the redeclared method will be

2605

# inherited.

2606

#

2607

# - If an http annotation is inherited, the path pattern will be

2608

# modified as follows. Any version prefix will be replaced by the

2609

# version of the including API plus the root path if specified.

2610

#

2611

# Example of a simple mixin:

2612

#

2613

# package google.acl.v1;

2614

# service AccessControl {

2615

# // Get the underlying ACL object.

2616

# rpc GetAcl(GetAclRequest) returns (Acl) {

2617

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2622

# service Storage {

2623

# // rpc GetAcl(GetAclRequest) returns (Acl);

2624

#

2625

# // Get a data record.

2626

# rpc GetData(GetDataRequest) returns (Data) {

2627

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2632

#

2633

# apis:

2634

# - name: google.storage.v2.Storage

2635

# mixins:

2636

# - name: google.acl.v1.AccessControl

2637

#

2638

# The mixin construct implies that all methods in `AccessControl` are

2639

# also declared with same name and request/response types in

2640

# `Storage`. A documentation generator or annotation processor will

2641

# see the effective `Storage.GetAcl` method after inherting

2642

# documentation and annotations as follows:

2643

#

2644

# service Storage {

2645

# // Get the underlying ACL object.

2646

# rpc GetAcl(GetAclRequest) returns (Acl) {

2647

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2653

#

2654

# If the `root` field in the mixin is specified, it should be a

2655

# relative path under which inherited HTTP paths are placed. Example:

2656

#

2657

# apis:

2658

# - name: google.storage.v2.Storage

2659

# mixins:

2660

# - name: google.acl.v1.AccessControl

2661

# root: acls

2662

#

2663

# This implies the following inherited HTTP annotation:

2664

#

2665

# service Storage {

2666

# // Get the underlying ACL object.

2667

# rpc GetAcl(GetAclRequest) returns (Acl) {

2668

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2673

# are rooted.

2674

"name": "A String", # The fully qualified name of the API which is included.

2675

},

2676

],

2677

"syntax": "A String", # The source syntax of the service.

2678

"version": "A String", # A version string for this api. If specified, must have the form

2679

# `major-version.minor-version`, as in `1.10`. If the minor version

2680

# is omitted, it defaults to zero. If the entire version field is

2681

# empty, the major version is derived from the package name, as

2682

# outlined below. If the field is not empty, the version in the

2683

# package name will be verified to be consistent with what is

2684

# provided here.

2685

#

2686

# The versioning schema uses [semantic

2687

# versioning](http://semver.org) where the major version number

2688

# indicates a breaking change and the minor version an additive,

2689

# non-breaking change. Both version numbers are signals to users

2690

# what to expect from different versions, and should be carefully

2691

# chosen based on the product plan.

2692

#

2693

# The major version is also reflected in the package name of the

2694

# API, which must end in `v<major-version>`, as in

2695

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2696

# be omitted. Zero major versions must only be used for

2697

# experimental, none-GA apis.

2698

"options": [ # Any metadata attached to the API.

2699

{ # A protocol buffer option, which can be attached to a message, field,

2700

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2701

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2702

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2703

# For custom options, it should be the fully-qualified name. For example,

2704

# `"google.api.http"`.

2705

"value": { # The option's value packed in an Any message. If the value is a primitive,

2706

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2707

# should be used. If the value is an enum, it should be stored as an int32

2708

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2709

"a_key": "", # Properties of the object. Contains field @type with type URL.

2710

},

2711

},

2712

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2713

"methods": [ # The methods of this api, in unspecified order.

2714

{ # Method represents a method of an api.

2715

"name": "A String", # The simple name of this method.

2716

"requestStreaming": True or False, # If true, the request is streamed.

2717

"responseTypeUrl": "A String", # The URL of the output message type.

2718

"requestTypeUrl": "A String", # A URL of the input message type.

2719

"responseStreaming": True or False, # If true, the response is streamed.

2720

"syntax": "A String", # The source syntax of this method.

2721

"options": [ # Any metadata attached to the method.

2722

{ # A protocol buffer option, which can be attached to a message, field,

2723

# enumeration, etc.

2724

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2725

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2726

# For custom options, it should be the fully-qualified name. For example,

2727

# `"google.api.http"`.

2728

"value": { # The option's value packed in an Any message. If the value is a primitive,

2729

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2730

# should be used. If the value is an enum, it should be stored as an int32

2731

# value using the google.protobuf.Int32Value type.

2732

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2738

},

2739

],

2740

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2741

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2749

# - google.foo.v1.AnotherError

2750

"rules": [ # The list of custom error rules that apply to individual API messages.

2751

#

2752

# **NOTE:** All service configuration rules follow "last one wins" order.

2753

{ # A custom error rule.

2754

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2755

# objects of this type will be filtered when they appear in error payload.

2756

"selector": "A String", # Selects messages to which this rule applies.

2757

#

2758

# Refer to selector for syntax details.

2759

},

2760

],

2761

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

2762

"A String",

2763

],

2764

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2765

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

2766

# usage.

2767

#

2768

# The quota configuration works this way:

2769

# - The service configuration defines a set of metrics.

2770

# - For API calls, the quota.metric_rules maps methods to metrics with

2771

# corresponding costs.

2772

# - The quota.limits defines limits on the metrics, which will be used for

2773

# quota checks at runtime.

2774

#

2775

# An example quota configuration in yaml format:

#

# quota:

#

# - name: apiWriteQpsPerProject

2780

# metric: library.googleapis.com/write_calls

2781

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

2787

# # except for the UpdateBook and DeleteBook methods. These two methods

2788

# # are mapped to the write_calls metric, with the UpdateBook method

2789

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

2794

# - selector: google.example.library.v1.LibraryService.UpdateBook

2795

# metric_costs:

2796

# library.googleapis.com/write_calls: 2

2797

# - selector: google.example.library.v1.LibraryService.DeleteBook

2798

# metric_costs:

2799

# library.googleapis.com/write_calls: 1

2800

#

2801

# Corresponding Metric definition:

2802

#

2803

# metrics:

2804

# - name: library.googleapis.com/read_calls

2805

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

2810

# display_name: Write requests

2811

# metric_kind: DELTA

2812

# value_type: INT64

2813

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

2814

# or more metrics.

2815

{ # Bind API methods to metrics. Binding a method to a metric causes that

2816

# metric's configured quota behaviors to apply to the method call.

2817

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

2818

# cost applied to each metric.

2819

#

2820

# The key of the map is the metric name, and the values are the amount

2821

# increased for the metric against which the quota limits are defined.

2822

# The value must not be negative.

2823

"a_key": "A String",

2824

},

2825

"selector": "A String", # Selects the methods to which this rule applies.

2826

#

2827

# Refer to selector for syntax details.

2828

},

2829

],

2830

"limits": [ # List of `QuotaLimit` definitions for the service.

2831

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

2832

# for a limit type. There can be at most one limit for a duration and limit

2833

# type combination defined within a `QuotaGroup`.

2834

"displayName": "A String", # User-visible display name for this limit.

2835

# Optional. If not set, the UI will provide a default display name based on

2836

# the quota configuration. This field can be used to override the default

2837

# display name generated from the configuration.

2838

"description": "A String", # Optional. User-visible, extended description for this quota limit.

2839

# Should be used only when more context is needed to understand this limit

2840

# than provided by the limit's display name (see: `display_name`).

2841

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

2842

# duration. This is the number of tokens assigned when a client

2843

# application developer activates the service for his/her project.

2844

#

2845

# Specifying a value of 0 will block all requests. This can be used if you

2846

# are provisioning quota to selected consumers and blocking others.

2847

# Similarly, a value of -1 will indicate an unlimited quota. No other

2848

# negative values are allowed.

2849

#

2850

# Used by group-based quotas only.

2851

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

2852

# the same metric will be checked together during runtime. The metric must be

2853

# defined within the service config.

2854

#

2855

# Used by metric-based quotas only.

2856

"values": { # Tiered limit values, currently only STANDARD is supported.

2857

"a_key": "A String",

2858

},

2859

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

2860

# duration. Client application developers can override the default limit up

2861

# to this maximum. If specified, this value cannot be set to a value less

2862

# than the default limit. If not specified, it is set to the default limit.

2863

#

2864

# To allow clients to apply overrides with no upper bound, set this to -1,

2865

# indicating unlimited maximum quota.

2866

#

2867

# Used by group-based quotas only.

2868

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

2869

# For duration longer than a day, only multiple of days is supported. We

2870

# support only "100s" and "1d" for now. Additional support will be added in

2871

# the future. "0" indicates indefinite duration.

2872

#

2873

# Used by group-based quotas only.

2874

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

2875

# The free tier is the number of tokens that will be subtracted from the

2876

# billed amount when billing is enabled.

2877

# This field can only be set on a limit with duration "1d", in a billable

2878

# group; it is invalid on any other limit. If this field is not set, it

2879

# defaults to 0, indicating that there is no free tier for this service.

2880

#

2881

# Used by group-based quotas only.

2882

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

2883

# Metric.unit. The supported unit kinds are determined by the quota

2884

# backend system.

2885

#

2886

# The [Google Service Control](https://cloud.google.com/service-control)

2887

# supports the following unit components:

2888

# * One of the time intevals:

2889

# * "/min" for quota every minute.

2890

# * "/d" for quota every 24 hours, starting 00:00 US Pacific Time.

2891

# * Otherwise the quota won't be reset by time, such as storage limit.

2892

# * One and only one of the granted containers:

2893

# * "/{project}" quota for a project

2894

#

2895

# Here are some examples:

2896

# * "1/min/{project}" for quota per minute per project.

2897

#

2898

# Note: the order of unit components is insignificant.

2899

# The "1" at the beginning is required to follow the metric unit syntax.

2900

#

2901

# Used by metric-based quotas only.

2902

"name": "A String", # Name of the quota limit. The name is used to refer to the limit when

2903

# overriding the default limit on per-consumer basis.

2904

#

2905

# For metric-based quota limits, the name must be provided, and it must be

2906

# unique within the service. The name can only include alphanumeric

2907

# characters as well as '-'.

2908

#

2909

# The maximum length of the limit name is 64 characters.

2910

#

2911

# The name of a limit is used as a unique identifier for this limit.

2912

# Therefore, once a limit has been put into use, its name should be

2913

# immutable. You can use the display_name field to provide a user-friendly

2914

# name for the limit. The display name can be evolved over time without

2915

# affecting the identity of the limit.

2916

},

2917

],

2918

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2919

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

2920

# elements. Restrictions are specified using visibility labels

2921

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2922

#

2923

# Users and projects can have access to more than one visibility label. The

2924

# effective visibility for multiple labels is the union of each label's

2925

# elements, plus any unrestricted elements.

2926

#

2927

# If an element and its parents have no restrictions, visibility is

2928

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2935

# restriction: TRUSTED_TESTER

2936

# - selector: google.calendar.Calendar.Delegate

2937

# restriction: GOOGLE_INTERNAL

2938

#

2939

# Here, all methods are publicly visible except for the restricted methods

2940

# EnhancedSearch and Delegate.

2941

"rules": [ # A list of visibility rules that apply to individual API elements.

2942

#

2943

# **NOTE:** All service configuration rules follow "last one wins" order.

2944

{ # A visibility rule provides visibility configuration for an individual API

2945

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2946

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

2947

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2948

#

2949

# If a rule has multiple labels, removing one of the labels but not all of

2950

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2957

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2958

#

2959

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2960

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2961

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2962

#

2963

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2968

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2969

# deleting or altering it stops data collection and makes the metric type's

2970

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2971

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2972

# Use sentence case without an ending period, for example "Request count".

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

2973

"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]

2974

"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]

2975

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2976

"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]

2977

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2978

"labels": [ # The set of labels that can be used to describe a specific

2979

# instance of this metric type. For example, the

2980

# `appengine.googleapis.com/http/server/response_latencies` metric

2981

# type has a label for the HTTP response code, `response_code`, so

2982

# you can look at latencies for successful responses or just

2983

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2984

{ # A description of a label.

2985

"valueType": "A String", # The type of data that can be assigned to the label.

2986

"description": "A String", # A human-readable description for the label.

2987

"key": "A String", # The label key.

2988

},

2989

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2990

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2991

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2992

# `custom.googleapis.com`. Metric types should use a natural hierarchical

2993

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2994

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2995

# "custom.googleapis.com/invoice/paid/amount"

2996

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2997

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2998

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2999

# supported units are a subset of [The Unified Code for Units of

3000

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3001

#

3002

# **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)

3017

# * `P` peta (10**15)

3018

# * `E` exa (10**18)

3019

# * `Z` zetta (10**21)

3020

# * `Y` yotta (10**24)

3021

# * `m` milli (10**-3)

3022

# * `u` micro (10**-6)

3023

# * `n` nano (10**-9)

3024

# * `p` pico (10**-12)

3025

# * `f` femto (10**-15)

3026

# * `a` atto (10**-18)

3027

# * `z` zepto (10**-21)

3028

# * `y` yocto (10**-24)

3029

# * `Ki` kibi (2**10)

3030

# * `Mi` mebi (2**20)

3031

# * `Gi` gibi (2**30)

3032

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

3037

#

3038

# The grammar also includes these connectors:

3039

#

3040

# * `/` division (as an infix operator, e.g. `1/s`).

3041

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

3042

#

3043

# The grammar for a unit is as follows:

3044

#

3045

# Expression = Component { "." Component } { "/" Component } ;

3046

#

3047

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

3057

# equivalent to `1` if it is used alone. For examples,

3058

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

3059

# * `NAME` is a sequence of non-blank printable ASCII characters not

3060

# containing '{' or '}'.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3061

"name": "A String", # The resource name of the metric descriptor. Depending on the

3062

# implementation, the name typically includes: (1) the parent resource name

3063

# that defines the scope of the metric type or of its data; and (2) the

3064

# metric's URL-encoded type, which also appears in the `type` field of this

3065

# descriptor. For example, following is the resource name of a custom

3066

# metric within the GCP project `my-project-id`:

3067

#

3068

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3069

},

3070

],

3071

"enums": [ # A list of all enum types included in this API service. Enums

3072

# referenced directly or indirectly by the `apis` are automatically

3073

# included. Enums which are not referenced but shall be included

3074

# should be listed here by name. Example:

3075

#

3076

# enums:

3077

# - name: google.someapi.v1.SomeEnum

3078

{ # Enum type definition.

3079

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3080

# protobuf element, like the file in which it is defined.

3081

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3082

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3083

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3084

"enumvalue": [ # Enum value definitions.

3085

{ # Enum value definition.

3086

"options": [ # Protocol buffer options.

3087

{ # A protocol buffer option, which can be attached to a message, field,

3088

# enumeration, etc.

3089

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3090

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3091

# For custom options, it should be the fully-qualified name. For example,

3092

# `"google.api.http"`.

3093

"value": { # The option's value packed in an Any message. If the value is a primitive,

3094

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3095

# should be used. If the value is an enum, it should be stored as an int32

3096

# value using the google.protobuf.Int32Value type.

3097

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

3102

"number": 42, # Enum value number.

3103

},

3104

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3105

"options": [ # Protocol buffer options.

3106

{ # A protocol buffer option, which can be attached to a message, field,

3107

# enumeration, etc.

3108

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3109

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3110

# For custom options, it should be the fully-qualified name. For example,

3111

# `"google.api.http"`.

3112

"value": { # The option's value packed in an Any message. If the value is a primitive,

3113

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3114

# should be used. If the value is an enum, it should be stored as an int32

3115

# value using the google.protobuf.Int32Value type.

3116

"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]

3121

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3122

},

3123

],

3124

"types": [ # A list of all proto message types included in this API service.

3125

# Types referenced directly or indirectly by the `apis` are

3126

# automatically included. Messages which are not referenced but

3127

# shall be included, such as types used by the `google.protobuf.Any` type,

3128

# should be listed here by name. Example:

3129

#

3130

# types:

3131

# - name: google.protobuf.Int32

3132

{ # A protocol buffer message type.

3133

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3134

"A String",

3135

],

3136

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3137

"fields": [ # The list of fields.

3138

{ # A single field of a message type.

3139

"kind": "A String", # The field type.

3140

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3141

# types. The first type has index 1; zero means the type is not in the list.

3142

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3143

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3144

"name": "A String", # The field name.

3145

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3146

"jsonName": "A String", # The field JSON name.

3147

"number": 42, # The field number.

3148

"cardinality": "A String", # The field cardinality.

3149

"options": [ # The protocol buffer options.

3150

{ # A protocol buffer option, which can be attached to a message, field,

3151

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3152

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3153

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3154

# For custom options, it should be the fully-qualified name. For example,

3155

# `"google.api.http"`.

3156

"value": { # The option's value packed in an Any message. If the value is a primitive,

3157

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3158

# should be used. If the value is an enum, it should be stored as an int32

3159

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3160

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3165

},

3166

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3167

"syntax": "A String", # The source syntax.

3168

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3169

# protobuf element, like the file in which it is defined.

3170

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3171

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3172

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3173

"options": [ # The protocol buffer options.

3174

{ # A protocol buffer option, which can be attached to a message, field,

3175

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3176

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3177

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3178

# For custom options, it should be the fully-qualified name. For example,

3179

# `"google.api.http"`.

3180

"value": { # The option's value packed in an Any message. If the value is a primitive,

3181

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3182

# should be used. If the value is an enum, it should be stored as an int32

3183

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3184

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3190

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3191

#

3192

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3193

# producer and consumer projects. In the example, the `activity_history`

3194

# log is sent to both the producer and consumer projects, whereas the

3195

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3196

#

3197

# monitored_resources:

3198

# - type: library.googleapis.com/branch

3199

# labels:

3200

# - key: /city

3201

# description: The city where the library branch is located in.

3202

# - key: /name

3203

# description: The name of the branch.

3204

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3205

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3206

# labels:

3207

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3208

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3209

# logging:

3210

# producer_destinations:

3211

# - monitored_resource: library.googleapis.com/branch

3212

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3213

# - activity_history

3214

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3215

# consumer_destinations:

3216

# - monitored_resource: library.googleapis.com/branch

3217

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3218

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3219

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

3220

# There can be multiple producer destinations, each one must have a

3221

# different monitored resource type. A log can be used in at most

3222

# one producer destination.

3223

{ # Configuration of a specific logging destination (the producer project

3224

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3225

"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]

3226

# Service.monitored_resources section.

3227

"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]

3228

# be defined in the Service.logs section. If the log name is

3229

# not a domain scoped name, it will be automatically prefixed with

3230

# 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.

3236

# There can be multiple consumer destinations, each one must have a

3237

# different monitored resource type. A log can be used in at most

3238

# one consumer destination.

3239

{ # Configuration of a specific logging destination (the producer project

3240

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

3241

"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]

3242

# Service.monitored_resources section.

3243

"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]

3244

# be defined in the Service.logs section. If the log name is

3245

# not a domain scoped name, it will be automatically prefixed with

3246

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

3253

# e.g. `calendar.googleapis.com`.

3254

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

3255

#

3256

# Example:

3257

# <pre><code>documentation:

3258

# summary: >

3259

# The Google Calendar API gives access

3260

# to most calendar features.

3261

# pages:

3262

# - name: Overview

3263

# content: (== include google/foo/overview.md ==)

3264

# - name: Tutorial

3265

# content: (== include google/foo/tutorial.md ==)

3266

# subpages;

3267

# - name: Java

3268

# content: (== include google/foo/tutorial_java.md ==)

3269

# rules:

3270

# - selector: google.calendar.Calendar.Get

3271

# description: >

3272

# ...

3273

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

3278

# standard markdown features, definition lists, tables and fenced

3279

# code blocks are supported. Section headers can be provided and are

3280

# interpreted relative to the section nesting of the context where

3281

# a documentation fragment is embedded.

3282

#

3283

# Documentation from the IDL is merged with documentation defined

3284

# via the config at normalization time, where documentation provided

3285

# by config rules overrides IDL provided.

3286

#

3287

# A number of constructs specific to the API platform are supported

3288

# in documentation text.

3289

#

3290

# In order to reference a proto element, the following

3291

# notation can be used:

3292

# <pre><code>[fully.qualified.proto.name][]</code></pre>

3293

# To override the display text used for the link, this can be used:

3294

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

3295

# Text can be excluded from doc using the following notation:

3296

# <pre><code>(-- internal comment --)</code></pre>

3297

# Comments can be made conditional using a visibility label. The below

3298

# text will be only rendered if the `BETA` label is available:

3299

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

3300

# A few directives are available in documentation. Note that

3301

# directives must appear on a single line to be properly

3302

# identified. The `include` directive includes a markdown file from

3303

# an external source:

3304

# <pre><code>(== include path/to/file ==)</code></pre>

3305

# The `resource_for` directive marks a message to be the resource of

3306

# a collection in REST view. If it is not specified, tools attempt

3307

# to infer the resource from the operations in a collection:

3308

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

3309

# The directive `suppress_warning` does not directly affect documentation

3310

# and is documented together with service config validation.

3311

"rules": [ # A list of documentation rules that apply to individual API elements.

3312

#

3313

# **NOTE:** All service configuration rules follow "last one wins" order.

3314

{ # A documentation rule provides information about individual API elements.

3315

"description": "A String", # Description of the selected API(s).

3316

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

3317

# element is marked as `deprecated`.

3318

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

3319

# qualified name of the element which may end in "*", indicating a wildcard.

3320

# Wildcards are only allowed at the end and for a whole component of the

3321

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

3322

# specify a default for all applicable elements, the whole pattern "*"

3323

# is used.

3324

},

3325

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3326

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3327

"overview": "A String", # Declares a single overview page. For example:

3328

# <pre><code>documentation:

3329

# summary: ...

3330

# overview: (== include overview.md ==)

3331

# </code></pre>

3332

# This is a shortcut for the following declaration (using pages style):

3333

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

3338

# </code></pre>

3339

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3340

"pages": [ # The top level pages for the documentation set.

3341

{ # Represents a documentation page. A page can contain subpages to represent

3342

# nested documentation set structure.

3343

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

3344

# to include content from a Markdown file.

3345

"subpages": [ # Subpages of this page. The order of subpages specified here will be

3346

# honored in the generated docset.

3347

# Object with schema name: Page

3348

],

3349

"name": "A String", # The name of the page. It will be used as an identity of the page to

3350

# generate URI of the page, text of the link to this page in navigation,

3351

# etc. The full page name (start from the root page name to this page

3352

# concatenated with `.`) can be used as reference to the page in your

3353

# documentation. For example:

3354

# <pre><code>pages:

3355

# - name: Tutorial

3356

# content: (== include tutorial.md ==)

3357

# subpages:

3358

# - name: Java

3359

# content: (== include tutorial_java.md ==)

3360

# </code></pre>

3361

# You can reference `Java` page using Markdown reference link syntax:

3362

# `Java`.

3363

},

3364

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

3365

"summary": "A String", # A short summary of what the service does. Can only be provided by

3366

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3367

},

3368

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

3369

"sourceFiles": [ # All files used during config generation.

3370

{

3371

"a_key": "", # Properties of the object. Contains field @type with type URL.

3372

},

3373

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3374

},

3375

"systemTypes": [ # A list of all proto message types included in this API service.

3376

# It serves similar purpose as [google.api.Service.types], except that

3377

# these types are not needed by user-defined APIs. Therefore, they will not

3378

# show up in the generated discovery doc. This field should only be used

3379

# to define system APIs in ESF.

3380

{ # A protocol buffer message type.

3381

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3382

"A String",

3383

],

3384

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3385

"fields": [ # The list of fields.

3386

{ # A single field of a message type.

3387

"kind": "A String", # The field type.

3388

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3389

# types. The first type has index 1; zero means the type is not in the list.

3390

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3391

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3392

"name": "A String", # The field name.

3393

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3394

"jsonName": "A String", # The field JSON name.

3395

"number": 42, # The field number.

3396

"cardinality": "A String", # The field cardinality.

3397

"options": [ # The protocol buffer options.

3398

{ # A protocol buffer option, which can be attached to a message, field,

3399

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3400

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3401

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3402

# For custom options, it should be the fully-qualified name. For example,

3403

# `"google.api.http"`.

3404

"value": { # The option's value packed in an Any message. If the value is a primitive,

3405

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3406

# should be used. If the value is an enum, it should be stored as an int32

3407

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3408

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3413

},

3414

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3415

"syntax": "A String", # The source syntax.

3416

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3417

# protobuf element, like the file in which it is defined.

3418

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3419

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3420

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3421

"options": [ # The protocol buffer options.

3422

{ # A protocol buffer option, which can be attached to a message, field,

3423

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3424

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3425

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3426

# For custom options, it should be the fully-qualified name. For example,

3427

# `"google.api.http"`.

3428

"value": { # The option's value packed in an Any message. If the value is a primitive,

3429

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3430

# should be used. If the value is an enum, it should be stored as an int32

3431

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3432

"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

3447

# - google.rpc.context.OriginContext

3448

#

3449

# The above specifies that all methods in the API request

3450

# `google.rpc.context.ProjectContext` and

3451

# `google.rpc.context.OriginContext`.

3452

#

3453

# Available context types are defined in package

3454

# `google.rpc.context`.

3455

"rules": [ # A list of RPC context rules that apply to individual API methods.

3456

#

3457

# **NOTE:** All service configuration rules follow "last one wins" order.

3458

{ # A context rule provides information about the context for an individual API

3459

# element.

3460

"provided": [ # A list of full type names of provided contexts.

3461

"A String",

3462

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3463

"selector": "A String", # Selects the methods to which this rule applies.

3464

#

3465

# Refer to selector for syntax details.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3466

"requested": [ # A list of full type names of requested contexts.

3467

"A String",

3468

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3469

},

3470

],

3471

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3472

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

3473

# with the same name as the service is automatically generated to service all

3474

# defined APIs.

3475

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

3476

# A service may expose any number of endpoints, and all endpoints share the

3477

# same service configuration, such as quota configuration and monitoring

3478

# configuration.

3479

#

3480

# Example service configuration:

3481

#

3482

# name: library-example.googleapis.com

3483

# endpoints:

3484

# # Below entry makes 'google.example.library.v1.Library'

3485

# # API be served from endpoint address library-example.googleapis.com.

3486

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

3487

# # it to decide whether the subsequent cross-origin request is

3488

# # allowed to proceed.

3489

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3490

# allow_cors: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3491

"target": "A String", # The specification of an Internet routable address of API frontend that will

3492

# handle requests to this [API Endpoint](https://cloud.google.com/apis/design/glossary).

3493

# It should be either a valid IPv4 address or a fully-qualified domain name.

3494

# For example, "8.8.8.8" or "myservice.appspot.com".

3495

"apis": [ # The list of APIs served by this endpoint.

3496

#

3497

# If no APIs are specified this translates to "all APIs" exported by the

3498

# service, as defined in the top-level service configuration.

3499

"A String",

3500

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3501

"allowCors": True or False, # Allowing

3502

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

3503

# cross-domain traffic, would allow the backends served from this endpoint to

3504

# receive and respond to HTTP OPTIONS requests. The response will be used by

3505

# the browser to determine whether the subsequent cross-origin request is

3506

# allowed to proceed.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3507

"name": "A String", # The canonical name of this endpoint.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3508

"features": [ # The list of features enabled on this endpoint.

3509

"A String",

3510

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3511

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

3512

# please specify multiple google.api.Endpoint for each of the intented

3513

# alias.

3514

#

3515

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3520

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

3521

# only be used by whitelisted users.

3522

"authorization": { # Configuration of authorization. # Authorization configuration.

3523

#

3524

# This section determines the authorization provider, if unspecified, then no

3525

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

3532

"provider": "A String", # The name of the authorization provider, such as

3533

# firebaserules.googleapis.com.

3534

},

3535

},

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]

3540

<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]

3541

<pre>Gets a service configuration (version) for a managed service.

3542

3543

Args:

3544

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3545

for naming requirements. For example: `example.googleapis.com`. (required)

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3546

configId: string, The id of the service configuration resource. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3547

x__xgafv: string, V1 error format.

3548

Allowed values

3549

1 - v1 error format

3550

2 - v2 error format

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3551

view: string, Specifies which parts of the Service Config should be returned in the

3552

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3553

3554

Returns:

3555

An object of the form:

3556

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3557

{ # `Service` is the root object of Google service configuration schema. It

3558

# describes basic information about a service, such as the name and the

3559

# title, and delegates other aspects to sub-sections. Each sub-section is

3560

# either a proto message or a repeated proto message that configures a

3561

# 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]

3566

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3567

# name: calendar.googleapis.com

3568

# title: Google Calendar API

3569

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3570

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3571

# authentication:

3572

# providers:

3573

# - id: google_calendar_auth

3574

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3575

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3576

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3577

# - selector: "*"

3578

# requirements:

3579

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3580

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3581

# service controller handles features like abuse, quota, billing, logging,

3582

# monitoring, etc.

3583

"environment": "A String", # The service control environment to use. If empty, no control plane

3584

# feature (like quota and billing) will be enabled.

3585

},

3586

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3587

# by the Service.monitoring and Service.logging configurations.

3588

{ # An object that describes the schema of a MonitoredResource object using a

3589

# type name and a set of labels. For example, the monitored resource

3590

# descriptor for Google Compute Engine VM instances has a type of

3591

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3592

# `"zone"` to identify particular VM instances.

3593

#

3594

# Different APIs can support different monitored resource types. APIs generally

3595

# provide a `list` method that returns the monitored resource descriptors used

3596

# by the API.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3597

"type": "A String", # Required. The monitored resource type. For example, the type

3598

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3599

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3600

"labels": [ # Required. A set of labels used to describe instances of this monitored

3601

# resource type. For example, an individual Google Cloud SQL database is

3602

# identified by values for the labels `"database_id"` and `"zone"`.

3603

{ # A description of a label.

3604

"valueType": "A String", # The type of data that can be assigned to the label.

3605

"description": "A String", # A human-readable description for the label.

3606

"key": "A String", # The label key.

3607

},

3608

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3609

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

3610

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3611

# without any article or other determiners. For example,

3612

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3613

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3614

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3615

# {type} is the value of the `type` field in this object and

3616

# {project_id} is a project ID that provides API-specific context for

3617

# accessing the type. APIs that do not use project information can use the

3618

# resource name format `"monitoredResourceDescriptors/{type}"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3619

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3620

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3621

},

3622

],

3623

"logs": [ # Defines the logs used by this service.

3624

{ # A description of a log type. Example in YAML format:

3625

#

3626

# - name: library.googleapis.com/activity_history

3627

# description: The history of borrowing and returning library items.

3628

# display_name: Activity

3629

# labels:

3630

# - key: /customer_id

3631

# description: Identifier of a library customer

3632

"labels": [ # The set of labels that are available to describe a specific log entry.

3633

# Runtime requests that contain labels not specified here are

3634

# considered invalid.

3635

{ # A description of a label.

3636

"valueType": "A String", # The type of data that can be assigned to the label.

3637

"description": "A String", # A human-readable description for the label.

3638

"key": "A String", # The label key.

3639

},

3640

],

3641

"displayName": "A String", # The human-readable name for this log. This information appears on

3642

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3643

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3644

# include the following characters: upper- and lower-case alphanumeric

3645

# characters [A-Za-z0-9], and punctuation characters including

3646

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3647

"description": "A String", # A human-readable description of this log. This information appears in

3648

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3649

},

3650

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3651

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3652

#

3653

# A system parameter is a special kind of parameter defined by the API

3654

# system, not by an individual API. It is typically mapped to an HTTP header

3655

# and/or a URL query parameter. This configuration specifies which methods

3656

# change the names of the system parameters.

3657

"rules": [ # Define system parameters.

3658

#

3659

# The parameters defined here will override the default parameters

3660

# implemented by the system. If this field is missing from the service

3661

# config, default system parameters will be used. Default system parameters

3662

# and names is implementation-dependent.

3663

#

3664

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3672

#

3673

#

3674

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3679

# parameters:

3680

# - name: api_key

3681

# http_header: Api-Key1

3682

# - name: api_key

3683

# http_header: Api-Key2

3684

#

3685

# **NOTE:** All service configuration rules follow "last one wins" order.

3686

{ # Define a system parameter rule mapping system parameter definitions to

3687

# methods.

3688

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3689

# For a given method call, only one of them should be used. If multiple

3690

# names are used the behavior is implementation-dependent.

3691

# If none of the specified names are present the behavior is

3692

# parameter-dependent.

3693

{ # Define a parameter's name and location. The parameter may be passed as either

3694

# an HTTP header or a URL query parameter, and if both are passed the behavior

3695

# is implementation-dependent.

3696

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3697

# sensitive.

3698

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

3699

# insensitive.

3700

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3701

},

3702

],

3703

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3704

# methods in all APIs.

3705

#

3706

# Refer to selector for syntax details.

3707

},

3708

],

3709

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3710

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3711

# by the client for tracking purpose. If empty, the server may choose to

3712

# generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3713

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3714

"rules": [ # A list of API backend rules that apply to individual API methods.

3715

#

3716

# **NOTE:** All service configuration rules follow "last one wins" order.

3717

{ # A backend rule provides configuration for an individual API element.

3718

"selector": "A String", # Selects the methods to which this rule applies.

3719

#

3720

# Refer to selector for syntax details.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3721

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

3722

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3723

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

3724

# default depends on the deployment context.

3725

"address": "A String", # The address of the API backend.

3726

},

3727

],

3728

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3729

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3730

#

3731

# The example below shows how to configure monitored resources and metrics

3732

# for monitoring. In the example, a monitored resource and two metrics are

3733

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3734

# to both producer and consumer projects, whereas the

3735

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3736

# consumer project.

3737

#

3738

# monitored_resources:

3739

# - type: library.googleapis.com/branch

3740

# labels:

3741

# - key: /city

3742

# description: The city where the library branch is located in.

3743

# - key: /name

3744

# description: The name of the branch.

3745

# metrics:

3746

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3751

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3756

# monitoring:

3757

# producer_destinations:

3758

# - monitored_resource: library.googleapis.com/branch

3759

# metrics:

3760

# - library.googleapis.com/book/returned_count

3761

# consumer_destinations:

3762

# - monitored_resource: library.googleapis.com/branch

3763

# metrics:

3764

# - library.googleapis.com/book/returned_count

3765

# - library.googleapis.com/book/overdue_count

3766

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3767

# There can be multiple producer destinations, each one must have a

3768

# different monitored resource type. A metric can be used in at most

3769

# one producer destination.

3770

{ # Configuration of a specific monitoring destination (the producer project

3771

# or the consumer project).

3772

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3773

# Service.monitored_resources section.

3774

"metrics": [ # Names of the metrics to report to this monitoring destination.

3775

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3781

# There can be multiple consumer destinations, each one must have a

3782

# different monitored resource type. A metric can be used in at most

3783

# one consumer destination.

3784

{ # Configuration of a specific monitoring destination (the producer project

3785

# or the consumer project).

3786

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3787

# Service.monitored_resources section.

3788

"metrics": [ # Names of the metrics to report to this monitoring destination.

3789

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3795

"title": "A String", # The product title associated with this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3796

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3797

#

3798

# Example for an API targeted for external use:

3799

#

3800

# name: calendar.googleapis.com

3801

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3802

# providers:

3803

# - id: google_calendar_auth

3804

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3805

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3806

# rules:

3807

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3808

# requirements:

3809

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3810

"rules": [ # A list of authentication rules that apply to individual API methods.

3811

#

3812

# **NOTE:** All service configuration rules follow "last one wins" order.

3813

{ # Authentication rules for the service.

3814

#

3815

# By default, if a method has any authentication requirements, every request

3816

# must include a valid credential matching one of the requirements.

3817

# It's an error to include more than one kind of credential in a single

3818

# request.

3819

#

3820

# If a method doesn't have any auth requirements, request credentials will be

3821

# ignored.

3822

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3823

# there are scopes defined for "Read-only access to Google Calendar" and

3824

# "Access to Cloud Platform". Users can consent to a scope for an application,

3825

# giving it permission to access that data on their behalf.

3826

#

3827

# OAuth scope specifications should be fairly coarse grained; a user will need

3828

# to see and understand the text description of what your scope means.

3829

#

3830

# In most cases: use one or at most two OAuth scopes for an entire family of

3831

# products. If your product has multiple APIs, you should probably be sharing

3832

# the OAuth scope across all of those APIs.

3833

#

3834

# When you need finer grained OAuth consent screens: talk with your product

3835

# management about how developers will use them in practice.

3836

#

3837

# Please note that even though each of the canonical scopes is enough for a

3838

# request to be accepted and passed to the backend, a request can still fail

3839

# due to the backend requiring additional scopes or permissions.

3840

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3841

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3846

# https://www.googleapis.com/auth/calendar.read

3847

},

3848

"requirements": [ # Requirements for additional authentication providers.

3849

{ # User-defined authentication requirements, including support for

3850

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3851

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3856

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3857

# implemented and accepted in all the runtime components.

3858

#

3859

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3860

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3861

# that are allowed to access. A JWT containing any of these audiences will

3862

# be accepted. When this setting is absent, only JWTs with audience

3863

# "https://Service_name/API_name"

3864

# will be accepted. For example, if no audiences are in the setting,

3865

# LibraryService API will only accept JWTs with the following audience

3866

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3871

# bookstore_web.apps.googleusercontent.com

3872

},

3873

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3874

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3875

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3876

#

3877

# For requests without credentials, if the service control environment is

3878

# specified, each incoming request **must** be associated with a service

3879

# consumer. This can be done by passing an API key that belongs to a consumer

3880

# project.

3881

"customAuth": { # Configuration for a custom authentication provider. # Configuration for custom authentication.

3882

"provider": "A String", # A configuration string containing connection information for the

3883

# authentication provider, typically formatted as a SmartService string

3884

# (go/smartservice).

3885

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3886

"selector": "A String", # Selects the methods to which this rule applies.

3887

#

3888

# Refer to selector for syntax details.

3889

},

3890

],

3891

"providers": [ # Defines a set of authentication providers that a service supports.

3892

{ # Configuration for an anthentication provider, including support for

3893

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3894

"audiences": "A String", # The list of JWT

3895

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3896

# that are allowed to access. A JWT containing any of these audiences will

3897

# be accepted. When this setting is absent, only JWTs with audience

3898

# "https://Service_name/API_name"

3899

# will be accepted. For example, if no audiences are in the setting,

3900

# LibraryService API will only accept JWTs with the following audience

3901

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3906

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3907

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3908

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3909

# Optional if the key set document:

3910

# - can be retrieved from

3911

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3912

# of the issuer.

3913

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3914

#

3915

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3916

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3917

# `AuthRequirement.provider_id`.

3918

#

3919

# Example: "bookstore_auth".

3920

"issuer": "A String", # Identifies the principal that issued the JWT. See

3921

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3922

# Usually a URL or an email address.

3923

#

3924

# Example: https://securetoken.google.com

3925

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3930

"rules": [ # A list of usage rules that apply to individual API methods.

3931

#

3932

# **NOTE:** All service configuration rules follow "last one wins" order.

3933

{ # Usage configuration rules for the service.

3934

#

3935

# NOTE: Under development.

3936

#

3937

#

3938

# Use this rule to configure unregistered calls for the service. Unregistered

3939

# calls are calls that do not contain consumer project identity.

3940

# (Example: calls that do not contain an API key).

3941

# By default, API methods do not allow unregistered calls, and each method call

3942

# must be identified by a consumer project identity. Use this rule to

3943

# allow/disallow unregistered calls.

3944

#

3945

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3951

#

3952

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3957

# allow_unregistered_calls: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3958

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3959

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3960

# methods in all APIs.

3961

#

3962

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3963

},

3964

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3965

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

3966

# service producer.

3967

#

3968

# Google Service Management currently only supports

3969

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

3970

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

3971

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

3972

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3973

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3974

# service. Each requirement is of the form <service.name>/<requirement-id>;

3975

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3980

# influence interpretation of the configuration, for example, to

3981

# determine defaults. This is documented together with applicable

3982

# options. The current default for the config version itself is `3`.

3983

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3984

# Members of this project can manage the service configuration,

3985

# manage consumption of the service, etc.

3986

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3987

# HttpRule, each specifying the mapping of an RPC method

3988

# to one or more HTTP REST API methods.

3989

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3990

#

3991

# **NOTE:** All service configuration rules follow "last one wins" order.

3992

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3993

# REST APIs. The mapping determines what portions of the request

3994

# message are populated from the path, query parameters, or body of

3995

# the HTTP request. The mapping is typically specified as an

3996

# `google.api.http` annotation, see "google/api/annotations.proto"

3997

# for details.

3998

#

3999

# The mapping consists of a field specifying the path template and

4000

# method kind. The path template can refer to fields in the request

4001

# message, as in the example below which describes a REST GET

4002

# operation on a resource collection of messages:

4003

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4004

#

4005

# service Messaging {

4006

# rpc GetMessage(GetMessageRequest) returns (Message) {

4007

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4008

# }

4009

# }

4010

# message GetMessageRequest {

4011

# message SubMessage {

4012

# string subfield = 1;

4013

# }

4014

# string message_id = 1; // mapped to the URL

4015

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4016

# }

4017

# message Message {

4018

# string text = 1; // content of the resource

4019

# }

4020

#

4021

# The same http annotation can alternatively be expressed inside the

4022

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

4027

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4028

#

4029

# This definition enables an automatic, bidrectional mapping of HTTP

4030

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4035

#

4036

# In general, not only fields but also field paths can be referenced

4037

# from a path pattern. Fields mapped to the path pattern cannot be

4038

# repeated and must have a primitive (non-message) type.

4039

#

4040

# Any fields in the request message which are not bound by the path

4041

# pattern automatically become (optional) HTTP query

4042

# parameters. Assume the following definition of the request message:

4043

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4044

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4045

# service Messaging {

4046

# rpc GetMessage(GetMessageRequest) returns (Message) {

4047

# option (google.api.http).get = "/v1/messages/{message_id}";

4048

# }

4049

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4050

# message GetMessageRequest {

4051

# message SubMessage {

4052

# string subfield = 1;

4053

# }

4054

# string message_id = 1; // mapped to the URL

4055

# int64 revision = 2; // becomes a parameter

4056

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

4057

# }

4058

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4059

#

4060

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

4065

#

4066

# Note that fields which are mapped to HTTP parameters must have a

4067

# primitive type or a repeated primitive type. Message types are not

4068

# allowed. In the case of a repeated type, the parameter can be

4069

# repeated in the URL, as in `...?param=A&param=B`.

4070

#

4071

# For HTTP method kinds which allow a request body, the `body` field

4072

# specifies the mapping. Consider a REST update method on the

4073

# message resource collection:

4074

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4075

#

4076

# service Messaging {

4077

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4078

# option (google.api.http) = {

4079

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4085

# string message_id = 1; // mapped to the URL

4086

# Message message = 2; // mapped to the body

4087

# }

4088

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4089

#

4090

# The following HTTP JSON to RPC mapping is enabled, where the

4091

# representation of the JSON in the request body is determined by

4092

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

4097

#

4098

# The special name `*` can be used in the body mapping to define that

4099

# every field not bound by the path template should be mapped to the

4100

# request body. This enables the following alternative definition of

4101

# the update method:

4102

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4103

# service Messaging {

4104

# rpc UpdateMessage(Message) returns (Message) {

4105

# option (google.api.http) = {

4106

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

4113

# string text = 2;

4114

# }

4115

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4116

#

4117

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

4122

#

4123

# Note that when using `*` in the body mapping, it is not possible to

4124

# have HTTP parameters, as all fields not bound by the path end in

4125

# the body. This makes this option more rarely used in practice of

4126

# defining REST APIs. The common usage of `*` is in custom methods

4127

# which don't use the URL at all for transferring data.

4128

#

4129

# It is possible to define multiple HTTP methods for one RPC by using

4130

# the `additional_bindings` option. Example:

4131

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4132

# service Messaging {

4133

# rpc GetMessage(GetMessageRequest) returns (Message) {

4134

# option (google.api.http) = {

4135

# get: "/v1/messages/{message_id}"

4136

# additional_bindings {

4137

# get: "/v1/users/{user_id}/messages/{message_id}"

4138

# }

4139

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4140

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4141

# }

4142

# message GetMessageRequest {

4143

# string message_id = 1;

4144

# string user_id = 2;

4145

# }

4146

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4147

#

4148

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4154

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

4155

#

4156

# # Rules for HTTP mapping

4157

#

4158

# The rules for mapping HTTP path, query parameters, and body fields

4159

# to the request message are as follows:

4160

#

4161

# 1. The `body` field specifies either `*` or a field path, or is

4162

# omitted. If omitted, it assumes there is no HTTP body.

4163

# 2. Leaf fields (recursive expansion of nested messages in the

4164

# request) can be classified into three types:

4165

# (a) Matched in the URL template.

4166

# (b) Covered by body (if body is `*`, everything except (a) fields;

4167

# else everything under the body field)

4168

# (c) All other fields.

4169

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

4170

# 4. Any body sent with an HTTP request can contain only (b) fields.

4171

#

4172

# The syntax of the path template is as follows:

4173

#

4174

# Template = "/" Segments [ Verb ] ;

4175

# Segments = Segment { "/" Segment } ;

4176

# Segment = "*" | "**" | LITERAL | Variable ;

4177

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4178

# FieldPath = IDENT { "." IDENT } ;

4179

# Verb = ":" LITERAL ;

4180

#

4181

# The syntax `*` matches a single path segment. It follows the semantics of

4182

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4183

# Expansion.

4184

#

4185

# The syntax `**` matches zero or more path segments. It follows the semantics

4186

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4187

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4188

#

4189

# The syntax `LITERAL` matches literal text in the URL path.

4190

#

4191

# The syntax `Variable` matches the entire path as specified by its template;

4192

# this nested template must not contain further variables. If a variable

4193

# matches a single path segment, its template may be omitted, e.g. `{var}`

4194

# is equivalent to `{var=*}`.

4195

#

4196

# NOTE: the field paths in variables and in the `body` must not refer to

4197

# repeated fields or map fields.

4198

#

4199

# Use CustomHttpPattern to specify any HTTP method that is not included in the

4200

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

4201

# a given URL path rule. The wild-card rule is useful for services that provide

4202

# content to Web (HTML) clients.

4203

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

4204

# `*` for mapping all fields not captured by the path pattern to the HTTP

4205

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4206

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4207

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4208

"restCollection": "A String", # Optional. The REST collection name is by default derived from the URL

4209

# pattern. If specified, this field overrides the default collection name.

4210

# Example:

4211

#

4212

# rpc AddressesAggregatedList(AddressesAggregatedListRequest)

4213

# returns (AddressesAggregatedListResponse) {

4214

# option (google.api.http) = {

4215

# get: "/v1/projects/{project_id}/aggregated/addresses"

4216

# rest_collection: "projects.addresses"

# };

# }

#

# This method has the automatically derived collection name

4221

# "projects.aggregated". Because, semantically, this rpc is actually an

4222

# operation on the "projects.addresses" collection, the `rest_collection`

4223

# field is configured to override the derived collection name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4224

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4225

# not contain an `additional_bindings` field themselves (that is,

4226

# the nesting may only be one level deep).

4227

# Object with schema name: HttpRule

4228

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4229

"mediaUpload": { # Defines the Media configuration for a service in case of an upload. # Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4230

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4231

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4232

# configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4233

# Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4234

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

4235

# your configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4236

"progressNotification": True or False, # Whether to receive a notification for progress changes of media upload.

4237

"startNotification": True or False, # Whether to receive a notification on the start of media upload.

4238

"mimeTypes": [ # An array of mimetype patterns. Esf will only accept uploads that match one

4239

# of the given patterns.

4240

"A String",

4241

],

4242

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of an

4243

# upload should be sent to the backend. These notifications will not be seen

4244

# by the client and will not consume quota.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4245

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4246

"uploadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4247

#

4248

# Specify name of the upload service if one is used for upload.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4249

"maxSize": "A String", # Optional maximum acceptable size for an upload.

4250

# The size is specified in bytes.

4251

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4252

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4253

"selector": "A String", # Selects methods to which this rule applies.

4254

#

4255

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4256

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

4257

# response. Other response fields are ignored. This field is optional. When

4258

# not set, the response message will be used as HTTP body of response.

4259

# NOTE: the referred field must be not a repeated field and must be present

4260

# at the top-level of response message type.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4261

"restMethodName": "A String", # Optional. The rest method name is by default derived from the URL

4262

# pattern. If specified, this field overrides the default method name.

4263

# Example:

4264

#

4265

# rpc CreateResource(CreateResourceRequest)

4266

# returns (CreateResourceResponse) {

4267

# option (google.api.http) = {

4268

# post: "/v1/resources",

4269

# body: "resource",

4270

# rest_method_name: "insert"

# };

# }

#

# This method has the automatically derived rest method name "create", but

4275

# for backwards compatability with apiary, it is specified as insert.

4276

"mediaDownload": { # Defines the Media configuration for a service in case of a download. # Use this only for Scotty Requests. Do not use this for bytestream methods.

4277

# For media support, add instead [][google.bytestream.RestByteStream] as an

4278

# API to your configuration.

4279

# Use this only for Scotty Requests. Do not use this for media support using

4280

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

4281

# your configuration for Bytestream methods.

4282

"useDirectDownload": True or False, # A boolean that determines if direct download from ESF should be used for

4283

# download of this media.

4284

"enabled": True or False, # Whether download is enabled.

4285

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of a

4286

# download should be sent to the backend.

4287

"maxDirectDownloadSize": "A String", # Optional maximum acceptable size for direct download.

4288

# The size is specified in bytes.

4289

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

4290

"downloadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

4291

#

4292

# Specify name of the download service if one is used for download.

4293

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4294

"put": "A String", # Used for updating a resource.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

4295

"patch": "A String", # Used for updating a resource.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4296

"post": "A String", # Used for creating a resource.

4297

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

4298

"path": "A String", # The path matched by this custom verb.

4299

"kind": "A String", # The name of this custom HTTP verb.

4300

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4301

"delete": "A String", # Used for deleting a resource.

4302

},

4303

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4304

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parmeters will be fully URI-decoded except in

4305

# cases of single segment matches in reserved expansion, where "%2F" will be

4306

# left encoded.

4307

#

4308

# The default behavior is to not decode RFC 6570 reserved characters in multi

4309

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4310

},

4311

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4312

# of the google.protobuf.Api needs to be provided by the configuration

4313

# author, as the remaining fields will be derived from the IDL during the

4314

# normalization process. It is an error to specify an API interface here

4315

# which cannot be resolved against the associated IDL files.

4316

{ # Api is a light-weight descriptor for a protocol buffer service.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4317

"name": "A String", # The fully qualified name of this api, including package name

4318

# followed by the api's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4319

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

4320

# message.

4321

# protobuf element, like the file in which it is defined.

4322

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4323

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4324

},

4325

"mixins": [ # Included APIs. See Mixin.

4326

{ # Declares an API to be included in this API. The including API must

4327

# redeclare all the methods from the included API, but documentation

4328

# and options are inherited as follows:

4329

#

4330

# - If after comment and whitespace stripping, the documentation

4331

# string of the redeclared method is empty, it will be inherited

4332

# from the original method.

4333

#

4334

# - Each annotation belonging to the service config (http,

4335

# visibility) which is not set in the redeclared method will be

4336

# inherited.

4337

#

4338

# - If an http annotation is inherited, the path pattern will be

4339

# modified as follows. Any version prefix will be replaced by the

4340

# version of the including API plus the root path if specified.

4341

#

4342

# Example of a simple mixin:

4343

#

4344

# package google.acl.v1;

4345

# service AccessControl {

4346

# // Get the underlying ACL object.

4347

# rpc GetAcl(GetAclRequest) returns (Acl) {

4348

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

4353

# service Storage {

4354

# // rpc GetAcl(GetAclRequest) returns (Acl);

4355

#

4356

# // Get a data record.

4357

# rpc GetData(GetDataRequest) returns (Data) {

4358

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

4363

#

4364

# apis:

4365

# - name: google.storage.v2.Storage

4366

# mixins:

4367

# - name: google.acl.v1.AccessControl

4368

#

4369

# The mixin construct implies that all methods in `AccessControl` are

4370

# also declared with same name and request/response types in

4371

# `Storage`. A documentation generator or annotation processor will

4372

# see the effective `Storage.GetAcl` method after inherting

4373

# documentation and annotations as follows:

4374

#

4375

# service Storage {

4376

# // Get the underlying ACL object.

4377

# rpc GetAcl(GetAclRequest) returns (Acl) {

4378

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

4384

#

4385

# If the `root` field in the mixin is specified, it should be a

4386

# relative path under which inherited HTTP paths are placed. Example:

4387

#

4388

# apis:

4389

# - name: google.storage.v2.Storage

4390

# mixins:

4391

# - name: google.acl.v1.AccessControl

4392

# root: acls

4393

#

4394

# This implies the following inherited HTTP annotation:

4395

#

4396

# service Storage {

4397

# // Get the underlying ACL object.

4398

# rpc GetAcl(GetAclRequest) returns (Acl) {

4399

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

4404

# are rooted.

4405

"name": "A String", # The fully qualified name of the API which is included.

4406

},

4407

],

4408

"syntax": "A String", # The source syntax of the service.

4409

"version": "A String", # A version string for this api. If specified, must have the form

4410

# `major-version.minor-version`, as in `1.10`. If the minor version

4411

# is omitted, it defaults to zero. If the entire version field is

4412

# empty, the major version is derived from the package name, as

4413

# outlined below. If the field is not empty, the version in the

4414

# package name will be verified to be consistent with what is

4415

# provided here.

4416

#

4417

# The versioning schema uses [semantic

4418

# versioning](http://semver.org) where the major version number

4419

# indicates a breaking change and the minor version an additive,

4420

# non-breaking change. Both version numbers are signals to users

4421

# what to expect from different versions, and should be carefully

4422

# chosen based on the product plan.

4423

#

4424

# The major version is also reflected in the package name of the

4425

# API, which must end in `v<major-version>`, as in

4426

# `google.feature.v1`. For major versions 0 and 1, the suffix can

4427

# be omitted. Zero major versions must only be used for

4428

# experimental, none-GA apis.

4429

"options": [ # Any metadata attached to the API.

4430

{ # A protocol buffer option, which can be attached to a message, field,

4431

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4432

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4433

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4434

# For custom options, it should be the fully-qualified name. For example,

4435

# `"google.api.http"`.

4436

"value": { # The option's value packed in an Any message. If the value is a primitive,

4437

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4438

# should be used. If the value is an enum, it should be stored as an int32

4439

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4440

"a_key": "", # Properties of the object. Contains field @type with type URL.

4441

},

4442

},

4443

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4444

"methods": [ # The methods of this api, in unspecified order.

4445

{ # Method represents a method of an api.

4446

"name": "A String", # The simple name of this method.

4447

"requestStreaming": True or False, # If true, the request is streamed.

4448

"responseTypeUrl": "A String", # The URL of the output message type.

4449

"requestTypeUrl": "A String", # A URL of the input message type.

4450

"responseStreaming": True or False, # If true, the response is streamed.

4451

"syntax": "A String", # The source syntax of this method.

4452

"options": [ # Any metadata attached to the method.

4453

{ # A protocol buffer option, which can be attached to a message, field,

4454

# enumeration, etc.

4455

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4456

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4457

# For custom options, it should be the fully-qualified name. For example,

4458

# `"google.api.http"`.

4459

"value": { # The option's value packed in an Any message. If the value is a primitive,

4460

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4461

# should be used. If the value is an enum, it should be stored as an int32

4462

# value using the google.protobuf.Int32Value type.

4463

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4469

},

4470

],

4471

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

4472

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

4480

# - google.foo.v1.AnotherError

4481

"rules": [ # The list of custom error rules that apply to individual API messages.

4482

#

4483

# **NOTE:** All service configuration rules follow "last one wins" order.

4484

{ # A custom error rule.

4485

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

4486

# objects of this type will be filtered when they appear in error payload.

4487

"selector": "A String", # Selects messages to which this rule applies.

4488

#

4489

# Refer to selector for syntax details.

4490

},

4491

],

4492

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

4493

"A String",

4494

],

4495

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4496

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

4497

# usage.

4498

#

4499

# The quota configuration works this way:

4500

# - The service configuration defines a set of metrics.

4501

# - For API calls, the quota.metric_rules maps methods to metrics with

4502

# corresponding costs.

4503

# - The quota.limits defines limits on the metrics, which will be used for

4504

# quota checks at runtime.

4505

#

4506

# An example quota configuration in yaml format:

#

# quota:

#

# - name: apiWriteQpsPerProject

4511

# metric: library.googleapis.com/write_calls

4512

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

4518

# # except for the UpdateBook and DeleteBook methods. These two methods

4519

# # are mapped to the write_calls metric, with the UpdateBook method

4520

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

4525

# - selector: google.example.library.v1.LibraryService.UpdateBook

4526

# metric_costs:

4527

# library.googleapis.com/write_calls: 2

4528

# - selector: google.example.library.v1.LibraryService.DeleteBook

4529

# metric_costs:

4530

# library.googleapis.com/write_calls: 1

4531

#

4532

# Corresponding Metric definition:

4533

#

4534

# metrics:

4535

# - name: library.googleapis.com/read_calls

4536

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

4541

# display_name: Write requests

4542

# metric_kind: DELTA

4543

# value_type: INT64

4544

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

4545

# or more metrics.

4546

{ # Bind API methods to metrics. Binding a method to a metric causes that

4547

# metric's configured quota behaviors to apply to the method call.

4548

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

4549

# cost applied to each metric.

4550

#

4551

# The key of the map is the metric name, and the values are the amount

4552

# increased for the metric against which the quota limits are defined.

4553

# The value must not be negative.

4554

"a_key": "A String",

4555

},

4556

"selector": "A String", # Selects the methods to which this rule applies.

4557

#

4558

# Refer to selector for syntax details.

4559

},

4560

],

4561

"limits": [ # List of `QuotaLimit` definitions for the service.

4562

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

4563

# for a limit type. There can be at most one limit for a duration and limit

4564

# type combination defined within a `QuotaGroup`.

4565

"displayName": "A String", # User-visible display name for this limit.

4566

# Optional. If not set, the UI will provide a default display name based on

4567

# the quota configuration. This field can be used to override the default

4568

# display name generated from the configuration.

4569

"description": "A String", # Optional. User-visible, extended description for this quota limit.

4570

# Should be used only when more context is needed to understand this limit

4571

# than provided by the limit's display name (see: `display_name`).

4572

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

4573

# duration. This is the number of tokens assigned when a client

4574

# application developer activates the service for his/her project.

4575

#

4576

# Specifying a value of 0 will block all requests. This can be used if you

4577

# are provisioning quota to selected consumers and blocking others.

4578

# Similarly, a value of -1 will indicate an unlimited quota. No other

4579

# negative values are allowed.

4580

#

4581

# Used by group-based quotas only.

4582

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

4583

# the same metric will be checked together during runtime. The metric must be

4584

# defined within the service config.

4585

#

4586

# Used by metric-based quotas only.

4587

"values": { # Tiered limit values, currently only STANDARD is supported.

4588

"a_key": "A String",

4589

},

4590

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

4591

# duration. Client application developers can override the default limit up

4592

# to this maximum. If specified, this value cannot be set to a value less

4593

# than the default limit. If not specified, it is set to the default limit.

4594

#

4595

# To allow clients to apply overrides with no upper bound, set this to -1,

4596

# indicating unlimited maximum quota.

4597

#

4598

# Used by group-based quotas only.

4599

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

4600

# For duration longer than a day, only multiple of days is supported. We

4601

# support only "100s" and "1d" for now. Additional support will be added in

4602

# the future. "0" indicates indefinite duration.

4603

#

4604

# Used by group-based quotas only.

4605

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

4606

# The free tier is the number of tokens that will be subtracted from the

4607

# billed amount when billing is enabled.

4608

# This field can only be set on a limit with duration "1d", in a billable

4609

# group; it is invalid on any other limit. If this field is not set, it

4610

# defaults to 0, indicating that there is no free tier for this service.

4611

#

4612

# Used by group-based quotas only.

4613

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

4614

# Metric.unit. The supported unit kinds are determined by the quota

4615

# backend system.

4616

#

4617

# The [Google Service Control](https://cloud.google.com/service-control)

4618

# supports the following unit components:

4619

# * One of the time intevals:

4620

# * "/min" for quota every minute.

4621

# * "/d" for quota every 24 hours, starting 00:00 US Pacific Time.

4622

# * Otherwise the quota won't be reset by time, such as storage limit.

4623

# * One and only one of the granted containers:

4624

# * "/{project}" quota for a project

4625

#

4626

# Here are some examples:

4627

# * "1/min/{project}" for quota per minute per project.

4628

#

4629

# Note: the order of unit components is insignificant.

4630

# The "1" at the beginning is required to follow the metric unit syntax.

4631

#

4632

# Used by metric-based quotas only.

4633

"name": "A String", # Name of the quota limit. The name is used to refer to the limit when

4634

# overriding the default limit on per-consumer basis.

4635

#

4636

# For metric-based quota limits, the name must be provided, and it must be

4637

# unique within the service. The name can only include alphanumeric

4638

# characters as well as '-'.

4639

#

4640

# The maximum length of the limit name is 64 characters.

4641

#

4642

# The name of a limit is used as a unique identifier for this limit.

4643

# Therefore, once a limit has been put into use, its name should be

4644

# immutable. You can use the display_name field to provide a user-friendly

4645

# name for the limit. The display name can be evolved over time without

4646

# affecting the identity of the limit.

4647

},

4648

],

4649

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4650

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

4651

# elements. Restrictions are specified using visibility labels

4652

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

4653

#

4654

# Users and projects can have access to more than one visibility label. The

4655

# effective visibility for multiple labels is the union of each label's

4656

# elements, plus any unrestricted elements.

4657

#

4658

# If an element and its parents have no restrictions, visibility is

4659

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4666

# restriction: TRUSTED_TESTER

4667

# - selector: google.calendar.Calendar.Delegate

4668

# restriction: GOOGLE_INTERNAL

4669

#

4670

# Here, all methods are publicly visible except for the restricted methods

4671

# EnhancedSearch and Delegate.

4672

"rules": [ # A list of visibility rules that apply to individual API elements.

4673

#

4674

# **NOTE:** All service configuration rules follow "last one wins" order.

4675

{ # A visibility rule provides visibility configuration for an individual API

4676

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4677

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

4678

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4679

#

4680

# If a rule has multiple labels, removing one of the labels but not all of

4681

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4688

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

4689

#

4690

# Removing GOOGLE_INTERNAL from this restriction will break clients that

4691

# rely on this method and only had access to it through GOOGLE_INTERNAL.

4692

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

4693

#

4694

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4699

{ # Defines a metric type and its schema. Once a metric descriptor is created,

4700

# deleting or altering it stops data collection and makes the metric type's

4701

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4702

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4703

# Use sentence case without an ending period, for example "Request count".

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4704

"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]

4705

"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]

4706

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4707

"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]

4708

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4709

"labels": [ # The set of labels that can be used to describe a specific

4710

# instance of this metric type. For example, the

4711

# `appengine.googleapis.com/http/server/response_latencies` metric

4712

# type has a label for the HTTP response code, `response_code`, so

4713

# you can look at latencies for successful responses or just

4714

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4715

{ # A description of a label.

4716

"valueType": "A String", # The type of data that can be assigned to the label.

4717

"description": "A String", # A human-readable description for the label.

4718

"key": "A String", # The label key.

4719

},

4720

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4721

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4722

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4723

# `custom.googleapis.com`. Metric types should use a natural hierarchical

4724

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4725

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4726

# "custom.googleapis.com/invoice/paid/amount"

4727

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4728

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

4729

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

4730

# supported units are a subset of [The Unified Code for Units of

4731

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4732

#

4733

# **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)

4748

# * `P` peta (10**15)

4749

# * `E` exa (10**18)

4750

# * `Z` zetta (10**21)

4751

# * `Y` yotta (10**24)

4752

# * `m` milli (10**-3)

4753

# * `u` micro (10**-6)

4754

# * `n` nano (10**-9)

4755

# * `p` pico (10**-12)

4756

# * `f` femto (10**-15)

4757

# * `a` atto (10**-18)

4758

# * `z` zepto (10**-21)

4759

# * `y` yocto (10**-24)

4760

# * `Ki` kibi (2**10)

4761

# * `Mi` mebi (2**20)

4762

# * `Gi` gibi (2**30)

4763

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

4768

#

4769

# The grammar also includes these connectors:

4770

#

4771

# * `/` division (as an infix operator, e.g. `1/s`).

4772

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

4773

#

4774

# The grammar for a unit is as follows:

4775

#

4776

# Expression = Component { "." Component } { "/" Component } ;

4777

#

4778

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

4788

# equivalent to `1` if it is used alone. For examples,

4789

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

4790

# * `NAME` is a sequence of non-blank printable ASCII characters not

4791

# containing '{' or '}'.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4792

"name": "A String", # The resource name of the metric descriptor. Depending on the

4793

# implementation, the name typically includes: (1) the parent resource name

4794

# that defines the scope of the metric type or of its data; and (2) the

4795

# metric's URL-encoded type, which also appears in the `type` field of this

4796

# descriptor. For example, following is the resource name of a custom

4797

# metric within the GCP project `my-project-id`:

4798

#

4799

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4800

},

4801

],

4802

"enums": [ # A list of all enum types included in this API service. Enums

4803

# referenced directly or indirectly by the `apis` are automatically

4804

# included. Enums which are not referenced but shall be included

4805

# should be listed here by name. Example:

4806

#

4807

# enums:

4808

# - name: google.someapi.v1.SomeEnum

4809

{ # Enum type definition.

4810

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4811

# protobuf element, like the file in which it is defined.

4812

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4813

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4814

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4815

"enumvalue": [ # Enum value definitions.

4816

{ # Enum value definition.

4817

"options": [ # Protocol buffer options.

4818

{ # A protocol buffer option, which can be attached to a message, field,

4819

# enumeration, etc.

4820

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4821

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4822

# For custom options, it should be the fully-qualified name. For example,

4823

# `"google.api.http"`.

4824

"value": { # The option's value packed in an Any message. If the value is a primitive,

4825

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4826

# should be used. If the value is an enum, it should be stored as an int32

4827

# value using the google.protobuf.Int32Value type.

4828

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

4833

"number": 42, # Enum value number.

4834

},

4835

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

4836

"options": [ # Protocol buffer options.

4837

{ # A protocol buffer option, which can be attached to a message, field,

4838

# enumeration, etc.

4839

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4840

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4841

# For custom options, it should be the fully-qualified name. For example,

4842

# `"google.api.http"`.

4843

"value": { # The option's value packed in an Any message. If the value is a primitive,

4844

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4845

# should be used. If the value is an enum, it should be stored as an int32

4846

# value using the google.protobuf.Int32Value type.

4847

"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]

4852

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4853

},

4854

],

4855

"types": [ # A list of all proto message types included in this API service.

4856

# Types referenced directly or indirectly by the `apis` are

4857

# automatically included. Messages which are not referenced but

4858

# shall be included, such as types used by the `google.protobuf.Any` type,

4859

# should be listed here by name. Example:

4860

#

4861

# types:

4862

# - name: google.protobuf.Int32

4863

{ # A protocol buffer message type.

4864

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4865

"A String",

4866

],

4867

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4868

"fields": [ # The list of fields.

4869

{ # A single field of a message type.

4870

"kind": "A String", # The field type.

4871

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4872

# types. The first type has index 1; zero means the type is not in the list.

4873

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4874

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4875

"name": "A String", # The field name.

4876

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4877

"jsonName": "A String", # The field JSON name.

4878

"number": 42, # The field number.

4879

"cardinality": "A String", # The field cardinality.

4880

"options": [ # The protocol buffer options.

4881

{ # A protocol buffer option, which can be attached to a message, field,

4882

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4883

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4884

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4885

# For custom options, it should be the fully-qualified name. For example,

4886

# `"google.api.http"`.

4887

"value": { # The option's value packed in an Any message. If the value is a primitive,

4888

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4889

# should be used. If the value is an enum, it should be stored as an int32

4890

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4891

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4896

},

4897

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4898

"syntax": "A String", # The source syntax.

4899

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4900

# protobuf element, like the file in which it is defined.

4901

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4902

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4903

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4904

"options": [ # The protocol buffer options.

4905

{ # A protocol buffer option, which can be attached to a message, field,

4906

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4907

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4908

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4909

# For custom options, it should be the fully-qualified name. For example,

4910

# `"google.api.http"`.

4911

"value": { # The option's value packed in an Any message. If the value is a primitive,

4912

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4913

# should be used. If the value is an enum, it should be stored as an int32

4914

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4915

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4921

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4922

#

4923

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4924

# producer and consumer projects. In the example, the `activity_history`

4925

# log is sent to both the producer and consumer projects, whereas the

4926

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4927

#

4928

# monitored_resources:

4929

# - type: library.googleapis.com/branch

4930

# labels:

4931

# - key: /city

4932

# description: The city where the library branch is located in.

4933

# - key: /name

4934

# description: The name of the branch.

4935

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4936

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4937

# labels:

4938

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4939

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4940

# logging:

4941

# producer_destinations:

4942

# - monitored_resource: library.googleapis.com/branch

4943

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4944

# - activity_history

4945

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4946

# consumer_destinations:

4947

# - monitored_resource: library.googleapis.com/branch

4948

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4949

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4950

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4951

# There can be multiple producer destinations, each one must have a

4952

# different monitored resource type. A log can be used in at most

4953

# one producer destination.

4954

{ # Configuration of a specific logging destination (the producer project

4955

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4956

"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]

4957

# Service.monitored_resources section.

4958

"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]

4959

# be defined in the Service.logs section. If the log name is

4960

# not a domain scoped name, it will be automatically prefixed with

4961

# 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.

4967

# There can be multiple consumer destinations, each one must have a

4968

# different monitored resource type. A log can be used in at most

4969

# one consumer destination.

4970

{ # Configuration of a specific logging destination (the producer project

4971

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4972

"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]

4973

# Service.monitored_resources section.

4974

"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]

4975

# be defined in the Service.logs section. If the log name is

4976

# not a domain scoped name, it will be automatically prefixed with

4977

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

4984

# e.g. `calendar.googleapis.com`.

4985

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4986

#

4987

# Example:

4988

# <pre><code>documentation:

4989

# summary: >

4990

# The Google Calendar API gives access

4991

# to most calendar features.

4992

# pages:

4993

# - name: Overview

4994

# content: (== include google/foo/overview.md ==)

4995

# - name: Tutorial

4996

# content: (== include google/foo/tutorial.md ==)

4997

# subpages;

4998

# - name: Java

4999

# content: (== include google/foo/tutorial_java.md ==)

5000

# rules:

5001

# - selector: google.calendar.Calendar.Get

5002

# description: >

5003

# ...

5004

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5009

# standard markdown features, definition lists, tables and fenced

5010

# code blocks are supported. Section headers can be provided and are

5011

# interpreted relative to the section nesting of the context where

5012

# a documentation fragment is embedded.

5013

#

5014

# Documentation from the IDL is merged with documentation defined

5015

# via the config at normalization time, where documentation provided

5016

# by config rules overrides IDL provided.

5017

#

5018

# A number of constructs specific to the API platform are supported

5019

# in documentation text.

5020

#

5021

# In order to reference a proto element, the following

5022

# notation can be used:

5023

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5024

# To override the display text used for the link, this can be used:

5025

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5026

# Text can be excluded from doc using the following notation:

5027

# <pre><code>(-- internal comment --)</code></pre>

5028

# Comments can be made conditional using a visibility label. The below

5029

# text will be only rendered if the `BETA` label is available:

5030

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5031

# A few directives are available in documentation. Note that

5032

# directives must appear on a single line to be properly

5033

# identified. The `include` directive includes a markdown file from

5034

# an external source:

5035

# <pre><code>(== include path/to/file ==)</code></pre>

5036

# The `resource_for` directive marks a message to be the resource of

5037

# a collection in REST view. If it is not specified, tools attempt

5038

# to infer the resource from the operations in a collection:

5039

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5040

# The directive `suppress_warning` does not directly affect documentation

5041

# and is documented together with service config validation.

5042

"rules": [ # A list of documentation rules that apply to individual API elements.

5043

#

5044

# **NOTE:** All service configuration rules follow "last one wins" order.

5045

{ # A documentation rule provides information about individual API elements.

5046

"description": "A String", # Description of the selected API(s).

5047

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5048

# element is marked as `deprecated`.

5049

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5050

# qualified name of the element which may end in "*", indicating a wildcard.

5051

# Wildcards are only allowed at the end and for a whole component of the

5052

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5053

# specify a default for all applicable elements, the whole pattern "*"

5054

# is used.

5055

},

5056

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5057

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5058

"overview": "A String", # Declares a single overview page. For example:

5059

# <pre><code>documentation:

5060

# summary: ...

5061

# overview: (== include overview.md ==)

5062

# </code></pre>

5063

# This is a shortcut for the following declaration (using pages style):

5064

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5069

# </code></pre>

5070

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5071

"pages": [ # The top level pages for the documentation set.

5072

{ # Represents a documentation page. A page can contain subpages to represent

5073

# nested documentation set structure.

5074

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5075

# to include content from a Markdown file.

5076

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5077

# honored in the generated docset.

5078

# Object with schema name: Page

5079

],

5080

"name": "A String", # The name of the page. It will be used as an identity of the page to

5081

# generate URI of the page, text of the link to this page in navigation,

5082

# etc. The full page name (start from the root page name to this page

5083

# concatenated with `.`) can be used as reference to the page in your

5084

# documentation. For example:

5085

# <pre><code>pages:

5086

# - name: Tutorial

5087

# content: (== include tutorial.md ==)

5088

# subpages:

5089

# - name: Java

5090

# content: (== include tutorial_java.md ==)

5091

# </code></pre>

5092

# You can reference `Java` page using Markdown reference link syntax:

5093

# `Java`.

5094

},

5095

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

5096

"summary": "A String", # A short summary of what the service does. Can only be provided by

5097

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5098

},

5099

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

5100

"sourceFiles": [ # All files used during config generation.

5101

{

5102

"a_key": "", # Properties of the object. Contains field @type with type URL.

5103

},

5104

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5105

},

5106

"systemTypes": [ # A list of all proto message types included in this API service.

5107

# It serves similar purpose as [google.api.Service.types], except that

5108

# these types are not needed by user-defined APIs. Therefore, they will not

5109

# show up in the generated discovery doc. This field should only be used

5110

# to define system APIs in ESF.

5111

{ # A protocol buffer message type.

5112

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5113

"A String",

5114

],

5115

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5116

"fields": [ # The list of fields.

5117

{ # A single field of a message type.

5118

"kind": "A String", # The field type.

5119

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5120

# types. The first type has index 1; zero means the type is not in the list.

5121

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5122

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5123

"name": "A String", # The field name.

5124

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5125

"jsonName": "A String", # The field JSON name.

5126

"number": 42, # The field number.

5127

"cardinality": "A String", # The field cardinality.

5128

"options": [ # The protocol buffer options.

5129

{ # A protocol buffer option, which can be attached to a message, field,

5130

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5131

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5132

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5133

# For custom options, it should be the fully-qualified name. For example,

5134

# `"google.api.http"`.

5135

"value": { # The option's value packed in an Any message. If the value is a primitive,

5136

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5137

# should be used. If the value is an enum, it should be stored as an int32

5138

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5139

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5144

},

5145

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5146

"syntax": "A String", # The source syntax.

5147

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5148

# protobuf element, like the file in which it is defined.

5149

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5150

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5151

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5152

"options": [ # The protocol buffer options.

5153

{ # A protocol buffer option, which can be attached to a message, field,

5154

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5155

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5156

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5157

# For custom options, it should be the fully-qualified name. For example,

5158

# `"google.api.http"`.

5159

"value": { # The option's value packed in an Any message. If the value is a primitive,

5160

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5161

# should be used. If the value is an enum, it should be stored as an int32

5162

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5163

"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

5178

# - google.rpc.context.OriginContext

5179

#

5180

# The above specifies that all methods in the API request

5181

# `google.rpc.context.ProjectContext` and

5182

# `google.rpc.context.OriginContext`.

5183

#

5184

# Available context types are defined in package

5185

# `google.rpc.context`.

5186

"rules": [ # A list of RPC context rules that apply to individual API methods.

5187

#

5188

# **NOTE:** All service configuration rules follow "last one wins" order.

5189

{ # A context rule provides information about the context for an individual API

5190

# element.

5191

"provided": [ # A list of full type names of provided contexts.

5192

"A String",

5193

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5194

"selector": "A String", # Selects the methods to which this rule applies.

5195

#

5196

# Refer to selector for syntax details.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5197

"requested": [ # A list of full type names of requested contexts.

5198

"A String",

5199

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5200

},

5201

],

5202

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5203

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5204

# with the same name as the service is automatically generated to service all

5205

# defined APIs.

5206

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5207

# A service may expose any number of endpoints, and all endpoints share the

5208

# same service configuration, such as quota configuration and monitoring

5209

# configuration.

5210

#

5211

# Example service configuration:

5212

#

5213

# name: library-example.googleapis.com

5214

# endpoints:

5215

# # Below entry makes 'google.example.library.v1.Library'

5216

# # API be served from endpoint address library-example.googleapis.com.

5217

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5218

# # it to decide whether the subsequent cross-origin request is

5219

# # allowed to proceed.

5220

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5221

# allow_cors: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5222

"target": "A String", # The specification of an Internet routable address of API frontend that will

5223

# handle requests to this [API Endpoint](https://cloud.google.com/apis/design/glossary).

5224

# It should be either a valid IPv4 address or a fully-qualified domain name.

5225

# For example, "8.8.8.8" or "myservice.appspot.com".

5226

"apis": [ # The list of APIs served by this endpoint.

5227

#

5228

# If no APIs are specified this translates to "all APIs" exported by the

5229

# service, as defined in the top-level service configuration.

5230

"A String",

5231

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5232

"allowCors": True or False, # Allowing

5233

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5234

# cross-domain traffic, would allow the backends served from this endpoint to

5235

# receive and respond to HTTP OPTIONS requests. The response will be used by

5236

# the browser to determine whether the subsequent cross-origin request is

5237

# allowed to proceed.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5238

"name": "A String", # The canonical name of this endpoint.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5239

"features": [ # The list of features enabled on this endpoint.

5240

"A String",

5241

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5242

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

5243

# please specify multiple google.api.Endpoint for each of the intented

5244

# alias.

5245

#

5246

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5251

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

5252

# only be used by whitelisted users.

5253

"authorization": { # Configuration of authorization. # Authorization configuration.

5254

#

5255

# This section determines the authorization provider, if unspecified, then no

5256

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

5263

"provider": "A String", # The name of the authorization provider, such as

5264

# firebaserules.googleapis.com.

5265

},

5266

},

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]

5271

<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]

5272

<pre>Lists the history of the service configuration for a managed service,

5273

from the newest to the oldest.

5274

5275

Args:

5276

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5277

for naming requirements. For example: `example.googleapis.com`. (required)

5278

pageSize: integer, The max number of items to include in the response list.

5279

pageToken: string, The token of the page to retrieve.

5280

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5287

5288

{ # Response message for ListServiceConfigs method.

5289

"nextPageToken": "A String", # The token of the next page of results.

5290

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5291

{ # `Service` is the root object of Google service configuration schema. It

5292

# describes basic information about a service, such as the name and the

5293

# title, and delegates other aspects to sub-sections. Each sub-section is

5294

# either a proto message or a repeated proto message that configures a

5295

# 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]

5300

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5301

# name: calendar.googleapis.com

5302

# title: Google Calendar API

5303

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5304

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5305

# authentication:

5306

# providers:

5307

# - id: google_calendar_auth

5308

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5309

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5310

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5311

# - selector: "*"

5312

# requirements:

5313

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5314

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

5315

# service controller handles features like abuse, quota, billing, logging,

5316

# monitoring, etc.

5317

"environment": "A String", # The service control environment to use. If empty, no control plane

5318

# feature (like quota and billing) will be enabled.

5319

},

5320

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

5321

# by the Service.monitoring and Service.logging configurations.

5322

{ # An object that describes the schema of a MonitoredResource object using a

5323

# type name and a set of labels. For example, the monitored resource

5324

# descriptor for Google Compute Engine VM instances has a type of

5325

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

5326

# `"zone"` to identify particular VM instances.

5327

#

5328

# Different APIs can support different monitored resource types. APIs generally

5329

# provide a `list` method that returns the monitored resource descriptors used

5330

# by the API.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5331

"type": "A String", # Required. The monitored resource type. For example, the type

5332

# `"cloudsql_database"` represents databases in Google Cloud SQL.

5333

# The maximum length of this value is 256 characters.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5334

"labels": [ # Required. A set of labels used to describe instances of this monitored

5335

# resource type. For example, an individual Google Cloud SQL database is

5336

# identified by values for the labels `"database_id"` and `"zone"`.

5337

{ # A description of a label.

5338

"valueType": "A String", # The type of data that can be assigned to the label.

5339

"description": "A String", # A human-readable description for the label.

5340

"key": "A String", # The label key.

5341

},

5342

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5343

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

5344

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

5345

# without any article or other determiners. For example,

5346

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5347

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

5348

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

5349

# {type} is the value of the `type` field in this object and

5350

# {project_id} is a project ID that provides API-specific context for

5351

# accessing the type. APIs that do not use project information can use the

5352

# resource name format `"monitoredResourceDescriptors/{type}"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5353

"description": "A String", # Optional. A detailed description of the monitored resource type that might

5354

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5355

},

5356

],

5357

"logs": [ # Defines the logs used by this service.

5358

{ # A description of a log type. Example in YAML format:

5359

#

5360

# - name: library.googleapis.com/activity_history

5361

# description: The history of borrowing and returning library items.

5362

# display_name: Activity

5363

# labels:

5364

# - key: /customer_id

5365

# description: Identifier of a library customer

5366

"labels": [ # The set of labels that are available to describe a specific log entry.

5367

# Runtime requests that contain labels not specified here are

5368

# considered invalid.

5369

{ # A description of a label.

5370

"valueType": "A String", # The type of data that can be assigned to the label.

5371

"description": "A String", # A human-readable description for the label.

5372

"key": "A String", # The label key.

5373

},

5374

],

5375

"displayName": "A String", # The human-readable name for this log. This information appears on

5376

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5377

"name": "A String", # The name of the log. It must be less than 512 characters long and can

5378

# include the following characters: upper- and lower-case alphanumeric

5379

# characters [A-Za-z0-9], and punctuation characters including

5380

# slash, underscore, hyphen, period [/_-.].

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5381

"description": "A String", # A human-readable description of this log. This information appears in

5382

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5383

},

5384

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5385

"systemParameters": { # ### System parameter configuration # System parameter configuration.

5386

#

5387

# A system parameter is a special kind of parameter defined by the API

5388

# system, not by an individual API. It is typically mapped to an HTTP header

5389

# and/or a URL query parameter. This configuration specifies which methods

5390

# change the names of the system parameters.

5391

"rules": [ # Define system parameters.

5392

#

5393

# The parameters defined here will override the default parameters

5394

# implemented by the system. If this field is missing from the service

5395

# config, default system parameters will be used. Default system parameters

5396

# and names is implementation-dependent.

5397

#

5398

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

5406

#

5407

#

5408

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

5413

# parameters:

5414

# - name: api_key

5415

# http_header: Api-Key1

5416

# - name: api_key

5417

# http_header: Api-Key2

5418

#

5419

# **NOTE:** All service configuration rules follow "last one wins" order.

5420

{ # Define a system parameter rule mapping system parameter definitions to

5421

# methods.

5422

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

5423

# For a given method call, only one of them should be used. If multiple

5424

# names are used the behavior is implementation-dependent.

5425

# If none of the specified names are present the behavior is

5426

# parameter-dependent.

5427

{ # Define a parameter's name and location. The parameter may be passed as either

5428

# an HTTP header or a URL query parameter, and if both are passed the behavior

5429

# is implementation-dependent.

5430

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

5431

# sensitive.

5432

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

5433

# insensitive.

5434

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

5435

},

5436

],

5437

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5438

# methods in all APIs.

5439

#

5440

# Refer to selector for syntax details.

5441

},

5442

],

5443

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5444

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5445

# by the client for tracking purpose. If empty, the server may choose to

5446

# generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5447

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

5448

"rules": [ # A list of API backend rules that apply to individual API methods.

5449

#

5450

# **NOTE:** All service configuration rules follow "last one wins" order.

5451

{ # A backend rule provides configuration for an individual API element.

5452

"selector": "A String", # Selects the methods to which this rule applies.

5453

#

5454

# Refer to selector for syntax details.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5455

"minDeadline": 3.14, # Minimum deadline in seconds needed for this method. Calls having deadline

5456

# value lower than this will be rejected.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5457

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

5458

# default depends on the deployment context.

5459

"address": "A String", # The address of the API backend.

5460

},

5461

],

5462

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5463

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5464

#

5465

# The example below shows how to configure monitored resources and metrics

5466

# for monitoring. In the example, a monitored resource and two metrics are

5467

# defined. The `library.googleapis.com/book/returned_count` metric is sent

5468

# to both producer and consumer projects, whereas the

5469

# `library.googleapis.com/book/overdue_count` metric is only sent to the

5470

# consumer project.

5471

#

5472

# monitored_resources:

5473

# - type: library.googleapis.com/branch

5474

# labels:

5475

# - key: /city

5476

# description: The city where the library branch is located in.

5477

# - key: /name

5478

# description: The name of the branch.

5479

# metrics:

5480

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

5485

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

5490

# monitoring:

5491

# producer_destinations:

5492

# - monitored_resource: library.googleapis.com/branch

5493

# metrics:

5494

# - library.googleapis.com/book/returned_count

5495

# consumer_destinations:

5496

# - monitored_resource: library.googleapis.com/branch

5497

# metrics:

5498

# - library.googleapis.com/book/returned_count

5499

# - library.googleapis.com/book/overdue_count

5500

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

5501

# There can be multiple producer destinations, each one must have a

5502

# different monitored resource type. A metric can be used in at most

5503

# one producer destination.

5504

{ # Configuration of a specific monitoring destination (the producer project

5505

# or the consumer project).

5506

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5507

# Service.monitored_resources section.

5508

"metrics": [ # Names of the metrics to report to this monitoring destination.

5509

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

5515

# There can be multiple consumer destinations, each one must have a

5516

# different monitored resource type. A metric can be used in at most

5517

# one consumer destination.

5518

{ # Configuration of a specific monitoring destination (the producer project

5519

# or the consumer project).

5520

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5521

# Service.monitored_resources section.

5522

"metrics": [ # Names of the metrics to report to this monitoring destination.

5523

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5529

"title": "A String", # The product title associated with this service.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5530

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

5531

#

5532

# Example for an API targeted for external use:

5533

#

5534

# name: calendar.googleapis.com

5535

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5536

# providers:

5537

# - id: google_calendar_auth

5538

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

5539

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5540

# rules:

5541

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5542

# requirements:

5543

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5544

"rules": [ # A list of authentication rules that apply to individual API methods.

5545

#

5546

# **NOTE:** All service configuration rules follow "last one wins" order.

5547

{ # Authentication rules for the service.

5548

#

5549

# By default, if a method has any authentication requirements, every request

5550

# must include a valid credential matching one of the requirements.

5551

# It's an error to include more than one kind of credential in a single

5552

# request.

5553

#

5554

# If a method doesn't have any auth requirements, request credentials will be

5555

# ignored.

5556

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

5557

# there are scopes defined for "Read-only access to Google Calendar" and

5558

# "Access to Cloud Platform". Users can consent to a scope for an application,

5559

# giving it permission to access that data on their behalf.

5560

#

5561

# OAuth scope specifications should be fairly coarse grained; a user will need

5562

# to see and understand the text description of what your scope means.

5563

#

5564

# In most cases: use one or at most two OAuth scopes for an entire family of

5565

# products. If your product has multiple APIs, you should probably be sharing

5566

# the OAuth scope across all of those APIs.

5567

#

5568

# When you need finer grained OAuth consent screens: talk with your product

5569

# management about how developers will use them in practice.

5570

#

5571

# Please note that even though each of the canonical scopes is enough for a

5572

# request to be accepted and passed to the backend, a request can still fail

5573

# due to the backend requiring additional scopes or permissions.

5574

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

5575

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

5580

# https://www.googleapis.com/auth/calendar.read

5581

},

5582

"requirements": [ # Requirements for additional authentication providers.

5583

{ # User-defined authentication requirements, including support for

5584

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

5585

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5590

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

5591

# implemented and accepted in all the runtime components.

5592

#

5593

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5594

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5595

# that are allowed to access. A JWT containing any of these audiences will

5596

# be accepted. When this setting is absent, only JWTs with audience

5597

# "https://Service_name/API_name"

5598

# will be accepted. For example, if no audiences are in the setting,

5599

# LibraryService API will only accept JWTs with the following audience

5600

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5605

# bookstore_web.apps.googleusercontent.com

5606

},

5607

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5608

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

5609

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

5610

#

5611

# For requests without credentials, if the service control environment is

5612

# specified, each incoming request **must** be associated with a service

5613

# consumer. This can be done by passing an API key that belongs to a consumer

5614

# project.

5615

"customAuth": { # Configuration for a custom authentication provider. # Configuration for custom authentication.

5616

"provider": "A String", # A configuration string containing connection information for the

5617

# authentication provider, typically formatted as a SmartService string

5618

# (go/smartservice).

5619

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5620

"selector": "A String", # Selects the methods to which this rule applies.

5621

#

5622

# Refer to selector for syntax details.

5623

},

5624

],

5625

"providers": [ # Defines a set of authentication providers that a service supports.

5626

{ # Configuration for an anthentication provider, including support for

5627

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5628

"audiences": "A String", # The list of JWT

5629

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

5630

# that are allowed to access. A JWT containing any of these audiences will

5631

# be accepted. When this setting is absent, only JWTs with audience

5632

# "https://Service_name/API_name"

5633

# will be accepted. For example, if no audiences are in the setting,

5634

# LibraryService API will only accept JWTs with the following audience

5635

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

5640

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5641

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

5642

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

5643

# Optional if the key set document:

5644

# - can be retrieved from

5645

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

5646

# of the issuer.

5647

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

5648

#

5649

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5650

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

5651

# `AuthRequirement.provider_id`.

5652

#

5653

# Example: "bookstore_auth".

5654

"issuer": "A String", # Identifies the principal that issued the JWT. See

5655

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

5656

# Usually a URL or an email address.

5657

#

5658

# Example: https://securetoken.google.com

5659

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

5664

"rules": [ # A list of usage rules that apply to individual API methods.

5665

#

5666

# **NOTE:** All service configuration rules follow "last one wins" order.

5667

{ # Usage configuration rules for the service.

5668

#

5669

# NOTE: Under development.

5670

#

5671

#

5672

# Use this rule to configure unregistered calls for the service. Unregistered

5673

# calls are calls that do not contain consumer project identity.

5674

# (Example: calls that do not contain an API key).

5675

# By default, API methods do not allow unregistered calls, and each method call

5676

# must be identified by a consumer project identity. Use this rule to

5677

# allow/disallow unregistered calls.

5678

#

5679

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

5685

#

5686

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

5691

# allow_unregistered_calls: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5692

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5693

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

5694

# methods in all APIs.

5695

#

5696

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5697

},

5698

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5699

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

5700

# service producer.

5701

#

5702

# Google Service Management currently only supports

5703

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

5704

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

5705

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

5706

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5707

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

5708

# service. Each requirement is of the form <service.name>/<requirement-id>;

5709

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

5714

# influence interpretation of the configuration, for example, to

5715

# determine defaults. This is documented together with applicable

5716

# options. The current default for the config version itself is `3`.

5717

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

5718

# Members of this project can manage the service configuration,

5719

# manage consumption of the service, etc.

5720

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

5721

# HttpRule, each specifying the mapping of an RPC method

5722

# to one or more HTTP REST API methods.

5723

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

5724

#

5725

# **NOTE:** All service configuration rules follow "last one wins" order.

5726

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

5727

# REST APIs. The mapping determines what portions of the request

5728

# message are populated from the path, query parameters, or body of

5729

# the HTTP request. The mapping is typically specified as an

5730

# `google.api.http` annotation, see "google/api/annotations.proto"

5731

# for details.

5732

#

5733

# The mapping consists of a field specifying the path template and

5734

# method kind. The path template can refer to fields in the request

5735

# message, as in the example below which describes a REST GET

5736

# operation on a resource collection of messages:

5737

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5738

#

5739

# service Messaging {

5740

# rpc GetMessage(GetMessageRequest) returns (Message) {

5741

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

5742

# }

5743

# }

5744

# message GetMessageRequest {

5745

# message SubMessage {

5746

# string subfield = 1;

5747

# }

5748

# string message_id = 1; // mapped to the URL

5749

# SubMessage sub = 2; // `sub.subfield` is url-mapped

5750

# }

5751

# message Message {

5752

# string text = 1; // content of the resource

5753

# }

5754

#

5755

# The same http annotation can alternatively be expressed inside the

5756

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

5761

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5762

#

5763

# This definition enables an automatic, bidrectional mapping of HTTP

5764

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

5769

#

5770

# In general, not only fields but also field paths can be referenced

5771

# from a path pattern. Fields mapped to the path pattern cannot be

5772

# repeated and must have a primitive (non-message) type.

5773

#

5774

# Any fields in the request message which are not bound by the path

5775

# pattern automatically become (optional) HTTP query

5776

# parameters. Assume the following definition of the request message:

5777

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5778

#

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5779

# service Messaging {

5780

# rpc GetMessage(GetMessageRequest) returns (Message) {

5781

# option (google.api.http).get = "/v1/messages/{message_id}";

5782

# }

5783

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5784

# message GetMessageRequest {

5785

# message SubMessage {

5786

# string subfield = 1;

5787

# }

5788

# string message_id = 1; // mapped to the URL

5789

# int64 revision = 2; // becomes a parameter

5790

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

5791

# }

5792

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5793

#

5794

# This enables a HTTP JSON to RPC mapping as below:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))`

5799

#

5800

# Note that fields which are mapped to HTTP parameters must have a

5801

# primitive type or a repeated primitive type. Message types are not

5802

# allowed. In the case of a repeated type, the parameter can be

5803

# repeated in the URL, as in `...?param=A&param=B`.

5804

#

5805

# For HTTP method kinds which allow a request body, the `body` field

5806

# specifies the mapping. Consider a REST update method on the

5807

# message resource collection:

5808

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5809

#

5810

# service Messaging {

5811

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

5812

# option (google.api.http) = {

5813

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

5819

# string message_id = 1; // mapped to the URL

5820

# Message message = 2; // mapped to the body

5821

# }

5822

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5823

#

5824

# The following HTTP JSON to RPC mapping is enabled, where the

5825

# representation of the JSON in the request body is determined by

5826

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

5831

#

5832

# The special name `*` can be used in the body mapping to define that

5833

# every field not bound by the path template should be mapped to the

5834

# request body. This enables the following alternative definition of

5835

# the update method:

5836

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5837

# service Messaging {

5838

# rpc UpdateMessage(Message) returns (Message) {

5839

# option (google.api.http) = {

5840

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

5847

# string text = 2;

5848

# }

5849

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5850

#

5851

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

5856

#

5857

# Note that when using `*` in the body mapping, it is not possible to

5858

# have HTTP parameters, as all fields not bound by the path end in

5859

# the body. This makes this option more rarely used in practice of

5860

# defining REST APIs. The common usage of `*` is in custom methods

5861

# which don't use the URL at all for transferring data.

5862

#

5863

# It is possible to define multiple HTTP methods for one RPC by using

5864

# the `additional_bindings` option. Example:

5865

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5866

# service Messaging {

5867

# rpc GetMessage(GetMessageRequest) returns (Message) {

5868

# option (google.api.http) = {

5869

# get: "/v1/messages/{message_id}"

5870

# additional_bindings {

5871

# get: "/v1/users/{user_id}/messages/{message_id}"

5872

# }

5873

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5874

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5875

# }

5876

# message GetMessageRequest {

5877

# string message_id = 1;

5878

# string user_id = 2;

5879

# }

5880

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5881

#

5882

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

5888

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

5889

#

5890

# # Rules for HTTP mapping

5891

#

5892

# The rules for mapping HTTP path, query parameters, and body fields

5893

# to the request message are as follows:

5894

#

5895

# 1. The `body` field specifies either `*` or a field path, or is

5896

# omitted. If omitted, it assumes there is no HTTP body.

5897

# 2. Leaf fields (recursive expansion of nested messages in the

5898

# request) can be classified into three types:

5899

# (a) Matched in the URL template.

5900

# (b) Covered by body (if body is `*`, everything except (a) fields;

5901

# else everything under the body field)

5902

# (c) All other fields.

5903

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

5904

# 4. Any body sent with an HTTP request can contain only (b) fields.

5905

#

5906

# The syntax of the path template is as follows:

5907

#

5908

# Template = "/" Segments [ Verb ] ;

5909

# Segments = Segment { "/" Segment } ;

5910

# Segment = "*" | "**" | LITERAL | Variable ;

5911

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5912

# FieldPath = IDENT { "." IDENT } ;

5913

# Verb = ":" LITERAL ;

5914

#

5915

# The syntax `*` matches a single path segment. It follows the semantics of

5916

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

5917

# Expansion.

5918

#

5919

# The syntax `**` matches zero or more path segments. It follows the semantics

5920

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5921

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5922

#

5923

# The syntax `LITERAL` matches literal text in the URL path.

5924

#

5925

# The syntax `Variable` matches the entire path as specified by its template;

5926

# this nested template must not contain further variables. If a variable

5927

# matches a single path segment, its template may be omitted, e.g. `{var}`

5928

# is equivalent to `{var=*}`.

5929

#

5930

# NOTE: the field paths in variables and in the `body` must not refer to

5931

# repeated fields or map fields.

5932

#

5933

# Use CustomHttpPattern to specify any HTTP method that is not included in the

5934

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

5935

# a given URL path rule. The wild-card rule is useful for services that provide

5936

# content to Web (HTML) clients.

5937

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

5938

# `*` for mapping all fields not captured by the path pattern to the HTTP

5939

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5940

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5941

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5942

"restCollection": "A String", # Optional. The REST collection name is by default derived from the URL

5943

# pattern. If specified, this field overrides the default collection name.

5944

# Example:

5945

#

5946

# rpc AddressesAggregatedList(AddressesAggregatedListRequest)

5947

# returns (AddressesAggregatedListResponse) {

5948

# option (google.api.http) = {

5949

# get: "/v1/projects/{project_id}/aggregated/addresses"

5950

# rest_collection: "projects.addresses"

# };

# }

#

# This method has the automatically derived collection name

5955

# "projects.aggregated". Because, semantically, this rpc is actually an

5956

# operation on the "projects.addresses" collection, the `rest_collection`

5957

# field is configured to override the derived collection name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5958

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

5959

# not contain an `additional_bindings` field themselves (that is,

5960

# the nesting may only be one level deep).

5961

# Object with schema name: HttpRule

5962

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5963

"mediaUpload": { # Defines the Media configuration for a service in case of an upload. # Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5964

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5965

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5966

# configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5967

# Use this only for Scotty Requests. Do not use this for media support using

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5968

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

5969

# your configuration for Bytestream methods.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5970

"progressNotification": True or False, # Whether to receive a notification for progress changes of media upload.

5971

"startNotification": True or False, # Whether to receive a notification on the start of media upload.

5972

"mimeTypes": [ # An array of mimetype patterns. Esf will only accept uploads that match one

5973

# of the given patterns.

5974

"A String",

5975

],

5976

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of an

5977

# upload should be sent to the backend. These notifications will not be seen

5978

# by the client and will not consume quota.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5979

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5980

"uploadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

5981

#

5982

# Specify name of the upload service if one is used for upload.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5983

"maxSize": "A String", # Optional maximum acceptable size for an upload.

5984

# The size is specified in bytes.

5985

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5986

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

5987

"selector": "A String", # Selects methods to which this rule applies.

5988

#

5989

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5990

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

5991

# response. Other response fields are ignored. This field is optional. When

5992

# not set, the response message will be used as HTTP body of response.

5993

# NOTE: the referred field must be not a repeated field and must be present

5994

# at the top-level of response message type.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

5995

"restMethodName": "A String", # Optional. The rest method name is by default derived from the URL

5996

# pattern. If specified, this field overrides the default method name.

5997

# Example:

5998

#

5999

# rpc CreateResource(CreateResourceRequest)

6000

# returns (CreateResourceResponse) {

6001

# option (google.api.http) = {

6002

# post: "/v1/resources",

6003

# body: "resource",

6004

# rest_method_name: "insert"

# };

# }

#

# This method has the automatically derived rest method name "create", but

6009

# for backwards compatability with apiary, it is specified as insert.

6010

"mediaDownload": { # Defines the Media configuration for a service in case of a download. # Use this only for Scotty Requests. Do not use this for bytestream methods.

6011

# For media support, add instead [][google.bytestream.RestByteStream] as an

6012

# API to your configuration.

6013

# Use this only for Scotty Requests. Do not use this for media support using

6014

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

6015

# your configuration for Bytestream methods.

6016

"useDirectDownload": True or False, # A boolean that determines if direct download from ESF should be used for

6017

# download of this media.

6018

"enabled": True or False, # Whether download is enabled.

6019

"completeNotification": True or False, # A boolean that determines whether a notification for the completion of a

6020

# download should be sent to the backend.

6021

"maxDirectDownloadSize": "A String", # Optional maximum acceptable size for direct download.

6022

# The size is specified in bytes.

6023

"dropzone": "A String", # Name of the Scotty dropzone to use for the current API.

6024

"downloadService": "A String", # DO NOT USE FIELDS BELOW THIS LINE UNTIL THIS WARNING IS REMOVED.

6025

#

6026

# Specify name of the download service if one is used for download.

6027

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6028

"put": "A String", # Used for updating a resource.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

6029

"patch": "A String", # Used for updating a resource.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6030

"post": "A String", # Used for creating a resource.

6031

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

6032

"path": "A String", # The path matched by this custom verb.

6033

"kind": "A String", # The name of this custom HTTP verb.

6034

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6035

"delete": "A String", # Used for deleting a resource.

6036

},

6037

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6038

"fullyDecodeReservedExpansion": True or False, # When set to true, URL path parmeters will be fully URI-decoded except in

6039

# cases of single segment matches in reserved expansion, where "%2F" will be

6040

# left encoded.

6041

#

6042

# The default behavior is to not decode RFC 6570 reserved characters in multi

6043

# segment matches.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6044

},

6045

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

6046

# of the google.protobuf.Api needs to be provided by the configuration

6047

# author, as the remaining fields will be derived from the IDL during the

6048

# normalization process. It is an error to specify an API interface here

6049

# which cannot be resolved against the associated IDL files.

6050

{ # Api is a light-weight descriptor for a protocol buffer service.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6051

"name": "A String", # The fully qualified name of this api, including package name

6052

# followed by the api's simple name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6053

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

6054

# message.

6055

# protobuf element, like the file in which it is defined.

6056

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6057

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6058

},

6059

"mixins": [ # Included APIs. See Mixin.

6060

{ # Declares an API to be included in this API. The including API must

6061

# redeclare all the methods from the included API, but documentation

6062

# and options are inherited as follows:

6063

#

6064

# - If after comment and whitespace stripping, the documentation

6065

# string of the redeclared method is empty, it will be inherited

6066

# from the original method.

6067

#

6068

# - Each annotation belonging to the service config (http,

6069

# visibility) which is not set in the redeclared method will be

6070

# inherited.

6071

#

6072

# - If an http annotation is inherited, the path pattern will be

6073

# modified as follows. Any version prefix will be replaced by the

6074

# version of the including API plus the root path if specified.

6075

#

6076

# Example of a simple mixin:

6077

#

6078

# package google.acl.v1;

6079

# service AccessControl {

6080

# // Get the underlying ACL object.

6081

# rpc GetAcl(GetAclRequest) returns (Acl) {

6082

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

6087

# service Storage {

6088

# // rpc GetAcl(GetAclRequest) returns (Acl);

6089

#

6090

# // Get a data record.

6091

# rpc GetData(GetDataRequest) returns (Data) {

6092

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

6097

#

6098

# apis:

6099

# - name: google.storage.v2.Storage

6100

# mixins:

6101

# - name: google.acl.v1.AccessControl

6102

#

6103

# The mixin construct implies that all methods in `AccessControl` are

6104

# also declared with same name and request/response types in

6105

# `Storage`. A documentation generator or annotation processor will

6106

# see the effective `Storage.GetAcl` method after inherting

6107

# documentation and annotations as follows:

6108

#

6109

# service Storage {

6110

# // Get the underlying ACL object.

6111

# rpc GetAcl(GetAclRequest) returns (Acl) {

6112

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

6118

#

6119

# If the `root` field in the mixin is specified, it should be a

6120

# relative path under which inherited HTTP paths are placed. Example:

6121

#

6122

# apis:

6123

# - name: google.storage.v2.Storage

6124

# mixins:

6125

# - name: google.acl.v1.AccessControl

6126

# root: acls

6127

#

6128

# This implies the following inherited HTTP annotation:

6129

#

6130

# service Storage {

6131

# // Get the underlying ACL object.

6132

# rpc GetAcl(GetAclRequest) returns (Acl) {

6133

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

6138

# are rooted.

6139

"name": "A String", # The fully qualified name of the API which is included.

6140

},

6141

],

6142

"syntax": "A String", # The source syntax of the service.

6143

"version": "A String", # A version string for this api. If specified, must have the form

6144

# `major-version.minor-version`, as in `1.10`. If the minor version

6145

# is omitted, it defaults to zero. If the entire version field is

6146

# empty, the major version is derived from the package name, as

6147

# outlined below. If the field is not empty, the version in the

6148

# package name will be verified to be consistent with what is

6149

# provided here.

6150

#

6151

# The versioning schema uses [semantic

6152

# versioning](http://semver.org) where the major version number

6153

# indicates a breaking change and the minor version an additive,

6154

# non-breaking change. Both version numbers are signals to users

6155

# what to expect from different versions, and should be carefully

6156

# chosen based on the product plan.

6157

#

6158

# The major version is also reflected in the package name of the

6159

# API, which must end in `v<major-version>`, as in

6160

# `google.feature.v1`. For major versions 0 and 1, the suffix can

6161

# be omitted. Zero major versions must only be used for

6162

# experimental, none-GA apis.

6163

"options": [ # Any metadata attached to the API.

6164

{ # A protocol buffer option, which can be attached to a message, field,

6165

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6166

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6167

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6168

# For custom options, it should be the fully-qualified name. For example,

6169

# `"google.api.http"`.

6170

"value": { # The option's value packed in an Any message. If the value is a primitive,

6171

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6172

# should be used. If the value is an enum, it should be stored as an int32

6173

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6174

"a_key": "", # Properties of the object. Contains field @type with type URL.

6175

},

6176

},

6177

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6178

"methods": [ # The methods of this api, in unspecified order.

6179

{ # Method represents a method of an api.

6180

"name": "A String", # The simple name of this method.

6181

"requestStreaming": True or False, # If true, the request is streamed.

6182

"responseTypeUrl": "A String", # The URL of the output message type.

6183

"requestTypeUrl": "A String", # A URL of the input message type.

6184

"responseStreaming": True or False, # If true, the response is streamed.

6185

"syntax": "A String", # The source syntax of this method.

6186

"options": [ # Any metadata attached to the method.

6187

{ # A protocol buffer option, which can be attached to a message, field,

6188

# enumeration, etc.

6189

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6190

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6191

# For custom options, it should be the fully-qualified name. For example,

6192

# `"google.api.http"`.

6193

"value": { # The option's value packed in an Any message. If the value is a primitive,

6194

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6195

# should be used. If the value is an enum, it should be stored as an int32

6196

# value using the google.protobuf.Int32Value type.

6197

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6203

},

6204

],

6205

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

6206

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

6214

# - google.foo.v1.AnotherError

6215

"rules": [ # The list of custom error rules that apply to individual API messages.

6216

#

6217

# **NOTE:** All service configuration rules follow "last one wins" order.

6218

{ # A custom error rule.

6219

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

6220

# objects of this type will be filtered when they appear in error payload.

6221

"selector": "A String", # Selects messages to which this rule applies.

6222

#

6223

# Refer to selector for syntax details.

6224

},

6225

],

6226

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

6227

"A String",

6228

],

6229

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6230

"quota": { # Quota configuration helps to achieve fairness and budgeting in service # Quota configuration.

6231

# usage.

6232

#

6233

# The quota configuration works this way:

6234

# - The service configuration defines a set of metrics.

6235

# - For API calls, the quota.metric_rules maps methods to metrics with

6236

# corresponding costs.

6237

# - The quota.limits defines limits on the metrics, which will be used for

6238

# quota checks at runtime.

6239

#

6240

# An example quota configuration in yaml format:

#

# quota:

#

# - name: apiWriteQpsPerProject

6245

# metric: library.googleapis.com/write_calls

6246

# unit: "1/min/{project}" # rate limit for consumer projects

# values:

# STANDARD: 10000

#

#

# # The metric rules bind all methods to the read_calls metric,

6252

# # except for the UpdateBook and DeleteBook methods. These two methods

6253

# # are mapped to the write_calls metric, with the UpdateBook method

6254

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

6259

# - selector: google.example.library.v1.LibraryService.UpdateBook

6260

# metric_costs:

6261

# library.googleapis.com/write_calls: 2

6262

# - selector: google.example.library.v1.LibraryService.DeleteBook

6263

# metric_costs:

6264

# library.googleapis.com/write_calls: 1

6265

#

6266

# Corresponding Metric definition:

6267

#

6268

# metrics:

6269

# - name: library.googleapis.com/read_calls

6270

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

6275

# display_name: Write requests

6276

# metric_kind: DELTA

6277

# value_type: INT64

6278

"metricRules": [ # List of `MetricRule` definitions, each one mapping a selected method to one

6279

# or more metrics.

6280

{ # Bind API methods to metrics. Binding a method to a metric causes that

6281

# metric's configured quota behaviors to apply to the method call.

6282

"metricCosts": { # Metrics to update when the selected methods are called, and the associated

6283

# cost applied to each metric.

6284

#

6285

# The key of the map is the metric name, and the values are the amount

6286

# increased for the metric against which the quota limits are defined.

6287

# The value must not be negative.

6288

"a_key": "A String",

6289

},

6290

"selector": "A String", # Selects the methods to which this rule applies.

6291

#

6292

# Refer to selector for syntax details.

6293

},

6294

],

6295

"limits": [ # List of `QuotaLimit` definitions for the service.

6296

{ # `QuotaLimit` defines a specific limit that applies over a specified duration

6297

# for a limit type. There can be at most one limit for a duration and limit

6298

# type combination defined within a `QuotaGroup`.

6299

"displayName": "A String", # User-visible display name for this limit.

6300

# Optional. If not set, the UI will provide a default display name based on

6301

# the quota configuration. This field can be used to override the default

6302

# display name generated from the configuration.

6303

"description": "A String", # Optional. User-visible, extended description for this quota limit.

6304

# Should be used only when more context is needed to understand this limit

6305

# than provided by the limit's display name (see: `display_name`).

6306

"defaultLimit": "A String", # Default number of tokens that can be consumed during the specified

6307

# duration. This is the number of tokens assigned when a client

6308

# application developer activates the service for his/her project.

6309

#

6310

# Specifying a value of 0 will block all requests. This can be used if you

6311

# are provisioning quota to selected consumers and blocking others.

6312

# Similarly, a value of -1 will indicate an unlimited quota. No other

6313

# negative values are allowed.

6314

#

6315

# Used by group-based quotas only.

6316

"metric": "A String", # The name of the metric this quota limit applies to. The quota limits with

6317

# the same metric will be checked together during runtime. The metric must be

6318

# defined within the service config.

6319

#

6320

# Used by metric-based quotas only.

6321

"values": { # Tiered limit values, currently only STANDARD is supported.

6322

"a_key": "A String",

6323

},

6324

"maxLimit": "A String", # Maximum number of tokens that can be consumed during the specified

6325

# duration. Client application developers can override the default limit up

6326

# to this maximum. If specified, this value cannot be set to a value less

6327

# than the default limit. If not specified, it is set to the default limit.

6328

#

6329

# To allow clients to apply overrides with no upper bound, set this to -1,

6330

# indicating unlimited maximum quota.

6331

#

6332

# Used by group-based quotas only.

6333

"duration": "A String", # Duration of this limit in textual notation. Example: "100s", "24h", "1d".

6334

# For duration longer than a day, only multiple of days is supported. We

6335

# support only "100s" and "1d" for now. Additional support will be added in

6336

# the future. "0" indicates indefinite duration.

6337

#

6338

# Used by group-based quotas only.

6339

"freeTier": "A String", # Free tier value displayed in the Developers Console for this limit.

6340

# The free tier is the number of tokens that will be subtracted from the

6341

# billed amount when billing is enabled.

6342

# This field can only be set on a limit with duration "1d", in a billable

6343

# group; it is invalid on any other limit. If this field is not set, it

6344

# defaults to 0, indicating that there is no free tier for this service.

6345

#

6346

# Used by group-based quotas only.

6347

"unit": "A String", # Specify the unit of the quota limit. It uses the same syntax as

6348

# Metric.unit. The supported unit kinds are determined by the quota

6349

# backend system.

6350

#

6351

# The [Google Service Control](https://cloud.google.com/service-control)

6352

# supports the following unit components:

6353

# * One of the time intevals:

6354

# * "/min" for quota every minute.

6355

# * "/d" for quota every 24 hours, starting 00:00 US Pacific Time.

6356

# * Otherwise the quota won't be reset by time, such as storage limit.

6357

# * One and only one of the granted containers:

6358

# * "/{project}" quota for a project

6359

#

6360

# Here are some examples:

6361

# * "1/min/{project}" for quota per minute per project.

6362

#

6363

# Note: the order of unit components is insignificant.

6364

# The "1" at the beginning is required to follow the metric unit syntax.

6365

#

6366

# Used by metric-based quotas only.

6367

"name": "A String", # Name of the quota limit. The name is used to refer to the limit when

6368

# overriding the default limit on per-consumer basis.

6369

#

6370

# For metric-based quota limits, the name must be provided, and it must be

6371

# unique within the service. The name can only include alphanumeric

6372

# characters as well as '-'.

6373

#

6374

# The maximum length of the limit name is 64 characters.

6375

#

6376

# The name of a limit is used as a unique identifier for this limit.

6377

# Therefore, once a limit has been put into use, its name should be

6378

# immutable. You can use the display_name field to provide a user-friendly

6379

# name for the limit. The display name can be evolved over time without

6380

# affecting the identity of the limit.

6381

},

6382

],

6383

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6384

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

6385

# elements. Restrictions are specified using visibility labels

6386

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

6387

#

6388

# Users and projects can have access to more than one visibility label. The

6389

# effective visibility for multiple labels is the union of each label's

6390

# elements, plus any unrestricted elements.

6391

#

6392

# If an element and its parents have no restrictions, visibility is

6393

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

6400

# restriction: TRUSTED_TESTER

6401

# - selector: google.calendar.Calendar.Delegate

6402

# restriction: GOOGLE_INTERNAL

6403

#

6404

# Here, all methods are publicly visible except for the restricted methods

6405

# EnhancedSearch and Delegate.

6406

"rules": [ # A list of visibility rules that apply to individual API elements.

6407

#

6408

# **NOTE:** All service configuration rules follow "last one wins" order.

6409

{ # A visibility rule provides visibility configuration for an individual API

6410

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6411

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

6412

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6413

#

6414

# If a rule has multiple labels, removing one of the labels but not all of

6415

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

6422

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

6423

#

6424

# Removing GOOGLE_INTERNAL from this restriction will break clients that

6425

# rely on this method and only had access to it through GOOGLE_INTERNAL.

6426

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

6427

#

6428

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6433

{ # Defines a metric type and its schema. Once a metric descriptor is created,

6434

# deleting or altering it stops data collection and makes the metric type's

6435

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6436

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

6437

# Use sentence case without an ending period, for example "Request count".

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6438

"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]

6439

"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]

6440

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6441

"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]

6442

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6443

"labels": [ # The set of labels that can be used to describe a specific

6444

# instance of this metric type. For example, the

6445

# `appengine.googleapis.com/http/server/response_latencies` metric

6446

# type has a label for the HTTP response code, `response_code`, so

6447

# you can look at latencies for successful responses or just

6448

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6449

{ # A description of a label.

6450

"valueType": "A String", # The type of data that can be assigned to the label.

6451

"description": "A String", # A human-readable description for the label.

6452

"key": "A String", # The label key.

6453

},

6454

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6455

"type": "A String", # The metric type, including its DNS name prefix. The type is not

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6456

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6457

# `custom.googleapis.com`. Metric types should use a natural hierarchical

6458

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6459

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6460

# "custom.googleapis.com/invoice/paid/amount"

6461

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6462

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

6463

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

6464

# supported units are a subset of [The Unified Code for Units of

6465

# Measure](http://unitsofmeasure.org/ucum.html) standard:

6466

#

6467

# **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)

6482

# * `P` peta (10**15)

6483

# * `E` exa (10**18)

6484

# * `Z` zetta (10**21)

6485

# * `Y` yotta (10**24)

6486

# * `m` milli (10**-3)

6487

# * `u` micro (10**-6)

6488

# * `n` nano (10**-9)

6489

# * `p` pico (10**-12)

6490

# * `f` femto (10**-15)

6491

# * `a` atto (10**-18)

6492

# * `z` zepto (10**-21)

6493

# * `y` yocto (10**-24)

6494

# * `Ki` kibi (2**10)

6495

# * `Mi` mebi (2**20)

6496

# * `Gi` gibi (2**30)

6497

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

6502

#

6503

# The grammar also includes these connectors:

6504

#

6505

# * `/` division (as an infix operator, e.g. `1/s`).

6506

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

6507

#

6508

# The grammar for a unit is as follows:

6509

#

6510

# Expression = Component { "." Component } { "/" Component } ;

6511

#

6512

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

6522

# equivalent to `1` if it is used alone. For examples,

6523

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

6524

# * `NAME` is a sequence of non-blank printable ASCII characters not

6525

# containing '{' or '}'.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6526

"name": "A String", # The resource name of the metric descriptor. Depending on the

6527

# implementation, the name typically includes: (1) the parent resource name

6528

# that defines the scope of the metric type or of its data; and (2) the

6529

# metric's URL-encoded type, which also appears in the `type` field of this

6530

# descriptor. For example, following is the resource name of a custom

6531

# metric within the GCP project `my-project-id`:

6532

#

6533

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6534

},

6535

],

6536

"enums": [ # A list of all enum types included in this API service. Enums

6537

# referenced directly or indirectly by the `apis` are automatically

6538

# included. Enums which are not referenced but shall be included

6539

# should be listed here by name. Example:

6540

#

6541

# enums:

6542

# - name: google.someapi.v1.SomeEnum

6543

{ # Enum type definition.

6544

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6545

# protobuf element, like the file in which it is defined.

6546

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6547

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6548

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6549

"enumvalue": [ # Enum value definitions.

6550

{ # Enum value definition.

6551

"options": [ # Protocol buffer options.

6552

{ # A protocol buffer option, which can be attached to a message, field,

6553

# enumeration, etc.

6554

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6555

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6556

# For custom options, it should be the fully-qualified name. For example,

6557

# `"google.api.http"`.

6558

"value": { # The option's value packed in an Any message. If the value is a primitive,

6559

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6560

# should be used. If the value is an enum, it should be stored as an int32

6561

# value using the google.protobuf.Int32Value type.

6562

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

6567

"number": 42, # Enum value number.

6568

},

6569

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6570

"options": [ # Protocol buffer options.

6571

{ # A protocol buffer option, which can be attached to a message, field,

6572

# enumeration, etc.

6573

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6574

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6575

# For custom options, it should be the fully-qualified name. For example,

6576

# `"google.api.http"`.

6577

"value": { # The option's value packed in an Any message. If the value is a primitive,

6578

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6579

# should be used. If the value is an enum, it should be stored as an int32

6580

# value using the google.protobuf.Int32Value type.

6581

"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]

6586

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6587

},

6588

],

6589

"types": [ # A list of all proto message types included in this API service.

6590

# Types referenced directly or indirectly by the `apis` are

6591

# automatically included. Messages which are not referenced but

6592

# shall be included, such as types used by the `google.protobuf.Any` type,

6593

# should be listed here by name. Example:

6594

#

6595

# types:

6596

# - name: google.protobuf.Int32

6597

{ # A protocol buffer message type.

6598

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6599

"A String",

6600

],

6601

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6602

"fields": [ # The list of fields.

6603

{ # A single field of a message type.

6604

"kind": "A String", # The field type.

6605

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6606

# types. The first type has index 1; zero means the type is not in the list.

6607

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6608

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6609

"name": "A String", # The field name.

6610

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6611

"jsonName": "A String", # The field JSON name.

6612

"number": 42, # The field number.

6613

"cardinality": "A String", # The field cardinality.

6614

"options": [ # The protocol buffer options.

6615

{ # A protocol buffer option, which can be attached to a message, field,

6616

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6617

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6618

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6619

# For custom options, it should be the fully-qualified name. For example,

6620

# `"google.api.http"`.

6621

"value": { # The option's value packed in an Any message. If the value is a primitive,

6622

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6623

# should be used. If the value is an enum, it should be stored as an int32

6624

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6625

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

6630

},

6631

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6632

"syntax": "A String", # The source syntax.

6633

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6634

# protobuf element, like the file in which it is defined.

6635

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6636

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6637

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6638

"options": [ # The protocol buffer options.

6639

{ # A protocol buffer option, which can be attached to a message, field,

6640

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6641

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6642

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6643

# For custom options, it should be the fully-qualified name. For example,

6644

# `"google.api.http"`.

6645

"value": { # The option's value packed in an Any message. If the value is a primitive,

6646

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6647

# should be used. If the value is an enum, it should be stored as an int32

6648

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6649

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6655

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6656

#

6657

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6658

# producer and consumer projects. In the example, the `activity_history`

6659

# log is sent to both the producer and consumer projects, whereas the

6660

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6661

#

6662

# monitored_resources:

6663

# - type: library.googleapis.com/branch

6664

# labels:

6665

# - key: /city

6666

# description: The city where the library branch is located in.

6667

# - key: /name

6668

# description: The name of the branch.

6669

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6670

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6671

# labels:

6672

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6673

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6674

# logging:

6675

# producer_destinations:

6676

# - monitored_resource: library.googleapis.com/branch

6677

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6678

# - activity_history

6679

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6680

# consumer_destinations:

6681

# - monitored_resource: library.googleapis.com/branch

6682

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6683

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6684

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

6685

# There can be multiple producer destinations, each one must have a

6686

# different monitored resource type. A log can be used in at most

6687

# one producer destination.

6688

{ # Configuration of a specific logging destination (the producer project

6689

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6690

"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]

6691

# Service.monitored_resources section.

6692

"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]

6693

# be defined in the Service.logs section. If the log name is

6694

# not a domain scoped name, it will be automatically prefixed with

6695

# 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.

6701

# There can be multiple consumer destinations, each one must have a

6702

# different monitored resource type. A log can be used in at most

6703

# one consumer destination.

6704

{ # Configuration of a specific logging destination (the producer project

6705

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6706

"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]

6707

# Service.monitored_resources section.

6708

"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]

6709

# be defined in the Service.logs section. If the log name is

6710

# not a domain scoped name, it will be automatically prefixed with

6711

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

6718

# e.g. `calendar.googleapis.com`.

6719

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

6720

#

6721

# Example:

6722

# <pre><code>documentation:

6723

# summary: >

6724

# The Google Calendar API gives access

6725

# to most calendar features.

6726

# pages:

6727

# - name: Overview

6728

# content: (== include google/foo/overview.md ==)

6729

# - name: Tutorial

6730

# content: (== include google/foo/tutorial.md ==)

6731

# subpages;

6732

# - name: Java

6733

# content: (== include google/foo/tutorial_java.md ==)

6734

# rules:

6735

# - selector: google.calendar.Calendar.Get

6736

# description: >

6737

# ...

6738

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

6743

# standard markdown features, definition lists, tables and fenced

6744

# code blocks are supported. Section headers can be provided and are

6745

# interpreted relative to the section nesting of the context where

6746

# a documentation fragment is embedded.

6747

#

6748

# Documentation from the IDL is merged with documentation defined

6749

# via the config at normalization time, where documentation provided

6750

# by config rules overrides IDL provided.

6751

#

6752

# A number of constructs specific to the API platform are supported

6753

# in documentation text.

6754

#

6755

# In order to reference a proto element, the following

6756

# notation can be used:

6757

# <pre><code>[fully.qualified.proto.name][]</code></pre>

6758

# To override the display text used for the link, this can be used:

6759

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

6760

# Text can be excluded from doc using the following notation:

6761

# <pre><code>(-- internal comment --)</code></pre>

6762

# Comments can be made conditional using a visibility label. The below

6763

# text will be only rendered if the `BETA` label is available:

6764

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

6765

# A few directives are available in documentation. Note that

6766

# directives must appear on a single line to be properly

6767

# identified. The `include` directive includes a markdown file from

6768

# an external source:

6769

# <pre><code>(== include path/to/file ==)</code></pre>

6770

# The `resource_for` directive marks a message to be the resource of

6771

# a collection in REST view. If it is not specified, tools attempt

6772

# to infer the resource from the operations in a collection:

6773

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

6774

# The directive `suppress_warning` does not directly affect documentation

6775

# and is documented together with service config validation.

6776

"rules": [ # A list of documentation rules that apply to individual API elements.

6777

#

6778

# **NOTE:** All service configuration rules follow "last one wins" order.

6779

{ # A documentation rule provides information about individual API elements.

6780

"description": "A String", # Description of the selected API(s).

6781

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

6782

# element is marked as `deprecated`.

6783

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

6784

# qualified name of the element which may end in "*", indicating a wildcard.

6785

# Wildcards are only allowed at the end and for a whole component of the

6786

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

6787

# specify a default for all applicable elements, the whole pattern "*"

6788

# is used.

6789

},

6790

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6791

"documentationRootUrl": "A String", # The URL to the root of documentation.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

6792

"overview": "A String", # Declares a single overview page. For example:

6793

# <pre><code>documentation:

6794

# summary: ...

6795

# overview: (== include overview.md ==)

6796

# </code></pre>

6797

# This is a shortcut for the following declaration (using pages style):

6798

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

6803

# </code></pre>

6804

# Note: you cannot specify both `overview` field and `pages` field.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6805

"pages": [ # The top level pages for the documentation set.

6806

{ # Represents a documentation page. A page can contain subpages to represent

6807

# nested documentation set structure.

6808

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

6809

# to include content from a Markdown file.

6810

"subpages": [ # Subpages of this page. The order of subpages specified here will be

6811

# honored in the generated docset.

6812

# Object with schema name: Page

6813

],

6814

"name": "A String", # The name of the page. It will be used as an identity of the page to

6815

# generate URI of the page, text of the link to this page in navigation,

6816

# etc. The full page name (start from the root page name to this page

6817

# concatenated with `.`) can be used as reference to the page in your

6818

# documentation. For example:

6819

# <pre><code>pages:

6820

# - name: Tutorial

6821

# content: (== include tutorial.md ==)

6822

# subpages:

6823

# - name: Java

6824

# content: (== include tutorial_java.md ==)

6825

# </code></pre>

6826

# You can reference `Java` page using Markdown reference link syntax:

6827

# `Java`.

6828

},

6829

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

6830

"summary": "A String", # A short summary of what the service does. Can only be provided by

6831

# plain text.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6832

},

6833

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

6834

"sourceFiles": [ # All files used during config generation.

6835

{

6836

"a_key": "", # Properties of the object. Contains field @type with type URL.

6837

},

6838

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6839

},

6840

"systemTypes": [ # A list of all proto message types included in this API service.

6841

# It serves similar purpose as [google.api.Service.types], except that

6842

# these types are not needed by user-defined APIs. Therefore, they will not

6843

# show up in the generated discovery doc. This field should only be used

6844

# to define system APIs in ESF.

6845

{ # A protocol buffer message type.

6846

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

6847

"A String",

6848

],

6849

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6850

"fields": [ # The list of fields.

6851

{ # A single field of a message type.

6852

"kind": "A String", # The field type.

6853

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

6854

# types. The first type has index 1; zero means the type is not in the list.

6855

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

6856

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

6857

"name": "A String", # The field name.

6858

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

6859

"jsonName": "A String", # The field JSON name.

6860

"number": 42, # The field number.

6861

"cardinality": "A String", # The field cardinality.

6862

"options": [ # The protocol buffer options.

6863

{ # A protocol buffer option, which can be attached to a message, field,

6864

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6865

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6866

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6867

# For custom options, it should be the fully-qualified name. For example,

6868

# `"google.api.http"`.

6869

"value": { # The option's value packed in an Any message. If the value is a primitive,

6870

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6871

# should be used. If the value is an enum, it should be stored as an int32

6872

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6873

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

6878

},

6879

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6880

"syntax": "A String", # The source syntax.

6881

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

6882

# protobuf element, like the file in which it is defined.

6883

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

6884

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

6885

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6886

"options": [ # The protocol buffer options.

6887

{ # A protocol buffer option, which can be attached to a message, field,

6888

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

6889

"name": "A String", # The option's name. For protobuf built-in options (options defined in

6890

# descriptor.proto), this is the short name. For example, `"map_entry"`.

6891

# For custom options, it should be the fully-qualified name. For example,

6892

# `"google.api.http"`.

6893

"value": { # The option's value packed in an Any message. If the value is a primitive,

6894

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

6895

# should be used. If the value is an enum, it should be stored as an int32

6896

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6897

"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

6912

# - google.rpc.context.OriginContext

6913

#

6914

# The above specifies that all methods in the API request

6915

# `google.rpc.context.ProjectContext` and

6916

# `google.rpc.context.OriginContext`.

6917

#

6918

# Available context types are defined in package

6919

# `google.rpc.context`.

6920

"rules": [ # A list of RPC context rules that apply to individual API methods.

6921

#

6922

# **NOTE:** All service configuration rules follow "last one wins" order.

6923

{ # A context rule provides information about the context for an individual API

6924

# element.

6925

"provided": [ # A list of full type names of provided contexts.

6926

"A String",

6927

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6928

"selector": "A String", # Selects the methods to which this rule applies.

6929

#

6930

# Refer to selector for syntax details.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6931

"requested": [ # A list of full type names of requested contexts.

6932

"A String",

6933

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

6934

},

6935

],

6936

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6937

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

6938

# with the same name as the service is automatically generated to service all

6939

# defined APIs.

6940

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

6941

# A service may expose any number of endpoints, and all endpoints share the

6942

# same service configuration, such as quota configuration and monitoring

6943

# configuration.

6944

#

6945

# Example service configuration:

6946

#

6947

# name: library-example.googleapis.com

6948

# endpoints:

6949

# # Below entry makes 'google.example.library.v1.Library'

6950

# # API be served from endpoint address library-example.googleapis.com.

6951

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

6952

# # it to decide whether the subsequent cross-origin request is

6953

# # allowed to proceed.

6954

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6955

# allow_cors: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6956

"target": "A String", # The specification of an Internet routable address of API frontend that will

6957

# handle requests to this [API Endpoint](https://cloud.google.com/apis/design/glossary).

6958

# It should be either a valid IPv4 address or a fully-qualified domain name.

6959

# For example, "8.8.8.8" or "myservice.appspot.com".

6960

"apis": [ # The list of APIs served by this endpoint.

6961

#

6962

# If no APIs are specified this translates to "all APIs" exported by the

6963

# service, as defined in the top-level service configuration.

6964

"A String",

6965

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6966

"allowCors": True or False, # Allowing

6967

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

6968

# cross-domain traffic, would allow the backends served from this endpoint to

6969

# receive and respond to HTTP OPTIONS requests. The response will be used by

6970

# the browser to determine whether the subsequent cross-origin request is

6971

# allowed to proceed.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6972

"name": "A String", # The canonical name of this endpoint.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6973

"features": [ # The list of features enabled on this endpoint.

6974

"A String",

6975

],

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6976

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

6977

# please specify multiple google.api.Endpoint for each of the intented

6978

# alias.

6979

#

6980

# Additional names that this endpoint will be hosted on.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6985

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

6986

# only be used by whitelisted users.

6987

"authorization": { # Configuration of authorization. # Authorization configuration.

6988

#

6989

# This section determines the authorization provider, if unspecified, then no

6990

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

6997

"provider": "A String", # The name of the authorization provider, such as

6998

# firebaserules.googleapis.com.

6999

},

7000

},

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>

7008

<pre>Retrieves the next page of results.

7009

7010

Args:

7011

previous_request: The request for the previous page. (required)

7012

previous_response: The response from the request for the previous page. (required)

7013

7014

Returns:

7015

A request object that you can call 'execute()' on to request the next

7016

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]

7021

<code class="details" id="submit">submit(serviceName, body, x__xgafv=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7022

<pre>Creates a new service configuration (version) for a managed service based

7023

on

7024

user-supplied configuration source files (for example: OpenAPI

7025

Specification). This method stores the source configurations as well as the

7026

generated service configuration. To rollout the service configuration to

7027

other services,

7028

please call CreateServiceRollout.

7029

7030

Operation<response: SubmitConfigSourceResponse>

7031

7032

Args:

7033

serviceName: string, The name of the service. See the [overview](/service-management/overview)

7034

for naming requirements. For example: `example.googleapis.com`. (required)

7035

body: object, The request body. (required)

7036

The object takes the form of:

7037

7038

{ # Request message for SubmitConfigSource method.

7039

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

7040

# `google.api.Service` configuration based on the `ConfigSource` provided,

7041

# but the generated config and the sources will NOT be persisted.

7042

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

7043

# defined by `google.api.Service`.

7044

"files": [ # Set of source configuration files that are used to generate a service

7045

# configuration (`google.api.Service`).

7046

{ # Generic specification of a source configuration file

7047

"fileContents": "A String", # The bytes that constitute the file.

7048

"fileType": "A String", # The type of configuration file this represents.

7049

"filePath": "A String", # The file name of the configuration file (full or relative path).

7050

},

7051

],

7052

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

7053

# by the client for tracking purpose. If empty, the server may choose to

7054

# 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:

7065

7066

{ # This resource represents a long-running operation that is the result of a

7067

# network API call.

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

7068

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7069

# programming environments, including REST APIs and RPC APIs. It is used by

7070

# [gRPC](https://github.com/grpc). The error model is designed to be:

7071

#

7072

# - Simple to use and understand for most users

7073

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

7078

# and error details. The error code should be an enum value of

7079

# google.rpc.Code, but it may accept additional error codes if needed. The

7080

# error message should be a developer-facing English message that helps

7081

# developers *understand* and *resolve* the error. If a localized user-facing

7082

# error message is needed, put the localized message in the error details or

7083

# localize it in the client. The optional error details may contain arbitrary

7084

# information about the error. There is a predefined set of error detail types

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7085

# in the package `google.rpc` that can be used for common error conditions.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

7090

# is not necessarily the actual wire format. When the `Status` message is

7091

# exposed in different client libraries and different wire protocols, it can be

7092

# mapped differently. For example, it will likely be mapped to some exceptions

7093

# in Java, but more likely mapped to some error codes in C.

#

# # Other uses

#

# The error model and the `Status` message can be used in a variety of

7098

# environments, either with or without APIs, to provide a

7099

# consistent developer experience across different environments.

7100

#

7101

# Example uses of this error model include:

7102

#

7103

# - Partial errors. If a service needs to return partial errors to the client,

7104

# it may embed the `Status` in the normal response to indicate the partial

7105

# errors.

7106

#

7107

# - Workflow errors. A typical workflow has multiple steps. Each step may

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7108

# have a `Status` message for error reporting.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

7109

#

7110

# - Batch operations. If a client uses batch request and batch response, the

7111

# `Status` message should be used directly inside batch response, one for

7112

# each error sub-response.

7113

#

7114

# - Asynchronous operations. If an API call embeds asynchronous operation

7115

# results in its response, the status of those operations should be

7116

# represented directly using the `Status` message.

7117

#

7118

# - Logging. If some API errors are stored in logs, the message `Status` could

7119

# be used directly after any stripping needed for security/privacy reasons.

7120

"message": "A String", # A developer-facing error message, which should be in English. Any

7121

# user-facing error message should be localized and sent in the

7122

# google.rpc.Status.details field, or localized by the client.

7123

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

7124

"details": [ # A list of messages that carry the error details. There will be a

7125

# common set of message types for APIs to use.

7126

{

7127

"a_key": "", # Properties of the object. Contains field @type with type URL.

7128

},

7129

],

7130

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7131

"done": True or False, # If the value is `false`, it means the operation is still in progress.

7132

# If true, the operation is completed, and either `error` or `response` is

7133

# available.

7134

"response": { # The normal response of the operation in case of success. If the original

7135

# method returns no data on success, such as `Delete`, the response is

7136

# `google.protobuf.Empty`. If the original method is standard

7137

# `Get`/`Create`/`Update`, the response should be the resource. For other

7138

# methods, the response should have the type `XxxResponse`, where `Xxx`

7139

# is the original method name. For example, if the original method name

7140

# is `TakeSnapshot()`, the inferred response type is

7141

# `TakeSnapshotResponse`.

7142

"a_key": "", # Properties of the object. Contains field @type with type URL.

7143

},

7144

"name": "A String", # The server-assigned name, which is only unique within the same service that

7145

# originally returns it. If you use the default HTTP mapping, the

7146

# `name` should have the format of `operations/some/unique/name`.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7147

"metadata": { # Service-specific metadata associated with the operation. It typically

7148

# contains progress information and common metadata such as create time.

7149

# Some services might not provide such metadata. Any method that returns a

7150

# long-running operation should document the metadata type, if any.

7151

"a_key": "", # Properties of the object. Contains field @type with type URL.

7152

},

Jon Wayne Parrott