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

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

[diff] [blame^]

81

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

84

<code><a href="#list">list(serviceName=None, pageSize=None, pageToken=None, x__xgafv=None)</a></code></p>

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

90

<code><a href="#submit">submit(serviceName=None, body, x__xgafv=None)</a></code></p>

91

<p class="firstline">Creates a new service configuration (version) for a managed service based</p>

92

<h3>Method Details</h3>

93

94

<code class="details" id="create">create(serviceName=None, body, x__xgafv=None)</code>

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.

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.

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

],

158

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

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

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 [/_-.].

Sai Cheemalapati

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

[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

],

Sai Cheemalapati

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

[diff] [blame^]

200

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

201

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

202

# generate one instead.

Jon Wayne Parrott

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

[diff] [blame]

203

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

204

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

205

#

206

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

207

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

208

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

209

#

210

# Refer to selector for syntax details.

211

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

212

# default depends on the deployment context.

213

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

214

},

215

],

216

},

Sai Cheemalapati

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

[diff] [blame]

217

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

Jon Wayne Parrott

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

[diff] [blame]

218

#

219

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

220

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

221

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

222

# to both producer and consumer projects, whereas the

223

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

224

# consumer project.

225

#

226

# monitored_resources:

227

# - type: library.googleapis.com/branch

228

# labels:

229

# - key: /city

230

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

231

# - key: /name

232

# description: The name of the branch.

233

# metrics:

234

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

239

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

244

# monitoring:

245

# producer_destinations:

246

# - monitored_resource: library.googleapis.com/branch

247

# metrics:

248

# - library.googleapis.com/book/returned_count

249

# consumer_destinations:

250

# - monitored_resource: library.googleapis.com/branch

251

# metrics:

252

# - library.googleapis.com/book/returned_count

253

# - library.googleapis.com/book/overdue_count

254

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

255

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

256

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

257

# one producer destination.

258

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

259

# or the consumer project).

260

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

261

# Service.monitored_resources section.

262

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

263

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

"A String",

],

},

],

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

269

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

270

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

271

# one consumer destination.

272

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

273

# or the consumer project).

274

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

275

# Service.monitored_resources section.

276

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

277

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

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame^]

283

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

284

#

285

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

286

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

287

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

288

# change the names of the system parameters.

289

"rules": [ # Define system parameters.

290

#

291

# The parameters defined here will override the default parameters

292

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

293

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

294

# and names is implementation-dependent.

295

#

296

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

304

#

305

#

306

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

311

# parameters:

312

# - name: api_key

313

# http_header: Api-Key1

314

# - name: api_key

315

# http_header: Api-Key2

316

#

317

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

318

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

319

# methods.

320

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

321

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

322

# names are used the behavior is implementation-dependent.

323

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

324

# parameter-dependent.

325

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

326

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

327

# is implementation-dependent.

328

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

329

# sensitive.

330

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

331

# insensitive.

332

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

333

},

334

],

335

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

336

# methods in all APIs.

337

#

338

# Refer to selector for syntax details.

339

},

340

],

341

},

Jon Wayne Parrott

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

[diff] [blame]

342

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

343

#

344

# Example for an API targeted for external use:

345

#

346

# name: calendar.googleapis.com

347

# authentication:

Jon Wayne Parrott

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

[diff] [blame]

348

# providers:

349

# - id: google_calendar_auth

350

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

351

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

Jon Wayne Parrott

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

[diff] [blame]

352

# rules:

353

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame]

354

# requirements:

355

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

356

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

357

#

358

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

359

{ # Authentication rules for the service.

360

#

361

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

362

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

363

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

364

# request.

365

#

366

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

367

# ignored.

368

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

369

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

370

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

371

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

372

#

373

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

374

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

375

#

376

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

377

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

378

# the OAuth scope across all of those APIs.

379

#

380

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

381

# management about how developers will use them in practice.

382

#

383

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

384

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

385

# due to the backend requiring additional scopes or permissions.

386

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

387

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

#

# Example:

#

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

392

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

393

},

Sai Cheemalapati

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

[diff] [blame^]

394

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

395

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

396

#

397

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

398

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

399

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

400

# project.

Jon Wayne Parrott

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

[diff] [blame]

401

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

402

{ # User-defined authentication requirements, including support for

403

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

404

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame]

409

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

410

# implemented and accepted in all the runtime components.

411

#

412

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

413

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

414

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

415

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

416

# "https://Service_name/API_name"

417

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

418

# LibraryService API will only accept JWTs with the following audience

419

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

424

# bookstore_web.apps.googleusercontent.com

425

},

426

],

Jon Wayne Parrott

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

[diff] [blame]

427

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

428

#

429

# Refer to selector for syntax details.

430

},

431

],

432

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

433

{ # Configuration for an anthentication provider, including support for

434

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

435

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

436

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

437

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

438

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

439

# "https://Service_name/API_name"

440

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

441

# LibraryService API will only accept JWTs with the following audience

442

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

447

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

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

[diff] [blame^]

448

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

449

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

450

# Optional if the key set document:

451

# - can be retrieved from

452

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

453

# of the issuer.

454

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

455

#

456

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

Jon Wayne Parrott

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

[diff] [blame]

457

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

458

# `AuthRequirement.provider_id`.

459

#

460

# Example: "bookstore_auth".

461

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

462

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

463

# Usually a URL or an email address.

464

#

465

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

466

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

},

],

},

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

471

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

472

#

473

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

474

{ # Usage configuration rules for the service.

475

#

476

# NOTE: Under development.

477

#

478

#

479

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

480

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

481

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

482

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

483

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

484

# allow/disallow unregistered calls.

485

#

486

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

492

#

493

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

#

# usage:

# rules:

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

498

# allow_unregistered_calls: true

499

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

500

# methods in all APIs.

501

#

502

# Refer to selector for syntax details.

503

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

504

},

505

],

Jon Wayne Parrott

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

[diff] [blame]

506

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

507

# service producer.

508

#

509

# Google Service Management currently only supports

510

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

511

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

512

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

513

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

Jon Wayne Parrott

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

[diff] [blame]

514

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

515

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

516

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

"A String",

],

},

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

521

# influence interpretation of the configuration, for example, to

522

# determine defaults. This is documented together with applicable

523

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

524

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

525

# Members of this project can manage the service configuration,

526

# manage consumption of the service, etc.

527

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

528

# HttpRule, each specifying the mapping of an RPC method

529

# to one or more HTTP REST API methods.

530

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

531

#

532

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

533

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

534

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

535

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

536

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

537

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

538

# for details.

539

#

540

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

541

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

542

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

543

# operation on a resource collection of messages:

544

#

Jon Wayne Parrott

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

[diff] [blame]

545

#

546

# service Messaging {

547

# rpc GetMessage(GetMessageRequest) returns (Message) {

548

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

549

# }

550

# }

551

# message GetMessageRequest {

552

# message SubMessage {

553

# string subfield = 1;

554

# }

555

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

556

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

557

# }

558

# message Message {

559

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

560

# }

561

#

562

# The same http annotation can alternatively be expressed inside the

563

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

568

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

Jon Wayne Parrott

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

[diff] [blame]

569

#

570

# This definition enables an automatic, bidrectional mapping of HTTP

571

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

576

#

577

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

578

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

579

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

580

#

581

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

582

# pattern automatically become (optional) HTTP query

583

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

584

#

Jon Wayne Parrott

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

[diff] [blame]

585

#

586

# message GetMessageRequest {

587

# message SubMessage {

588

# string subfield = 1;

589

# }

590

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

591

# int64 revision = 2; // becomes a parameter

592

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

593

# }

594

#

Jon Wayne Parrott

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

[diff] [blame]

595

#

596

# 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"))`

601

#

602

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

603

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

604

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

605

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

606

#

607

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

608

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

609

# message resource collection:

610

#

Jon Wayne Parrott

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

[diff] [blame]

611

#

612

# service Messaging {

613

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

614

# option (google.api.http) = {

615

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

621

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

622

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

623

# }

624

#

Jon Wayne Parrott

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

[diff] [blame]

625

#

626

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

627

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

628

# protos JSON encoding:

#

# HTTP | RPC

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

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

633

#

634

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

635

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

636

# request body. This enables the following alternative definition of

637

# the update method:

638

#

Jon Wayne Parrott

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

[diff] [blame]

639

# service Messaging {

640

# rpc UpdateMessage(Message) returns (Message) {

641

# option (google.api.http) = {

642

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

649

# string text = 2;

650

# }

651

#

Jon Wayne Parrott

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

[diff] [blame]

652

#

653

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

658

#

659

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

660

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

661

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

662

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

663

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

664

#

665

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

666

# the `additional_bindings` option. Example:

667

#

Jon Wayne Parrott

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

[diff] [blame]

668

# service Messaging {

669

# rpc GetMessage(GetMessageRequest) returns (Message) {

670

# option (google.api.http) = {

671

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

672

# additional_bindings {

673

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

674

# }

675

# };

Jon Wayne Parrott

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

[diff] [blame]

676

# }

Jon Wayne Parrott

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

[diff] [blame]

677

# }

678

# message GetMessageRequest {

679

# string message_id = 1;

680

# string user_id = 2;

681

# }

682

#

Jon Wayne Parrott

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

[diff] [blame]

683

#

684

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

690

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

691

#

692

# # Rules for HTTP mapping

693

#

694

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

695

# to the request message are as follows:

696

#

697

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

698

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

699

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

700

# request) can be classified into three types:

701

# (a) Matched in the URL template.

702

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

703

# else everything under the body field)

704

# (c) All other fields.

705

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

706

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

707

#

708

# The syntax of the path template is as follows:

709

#

710

# Template = "/" Segments [ Verb ] ;

711

# Segments = Segment { "/" Segment } ;

712

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

713

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

714

# FieldPath = IDENT { "." IDENT } ;

715

# Verb = ":" LITERAL ;

716

#

717

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

718

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

719

# Expansion.

720

#

721

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

722

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

723

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

724

#

725

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

726

#

727

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

728

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

729

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

730

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

731

#

732

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

733

# repeated fields or map fields.

734

#

735

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

736

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

737

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

738

# content to Web (HTML) clients.

739

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

740

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

741

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

742

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

Jon Wayne Parrott

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

[diff] [blame]

743

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

Sai Cheemalapati

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

[diff] [blame^]

744

"mediaDownload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for bytestream methods.

745

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

746

# API to your configuration.

747

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

748

# your configuration for Bytestream methods.

Jon Wayne Parrott

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

[diff] [blame]

749

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

Sai Cheemalapati

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

[diff] [blame^]

750

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

751

#

752

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

Jon Wayne Parrott

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

[diff] [blame]

753

},

754

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

755

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

756

# the nesting may only be one level deep).

757

# Object with schema name: HttpRule

758

],

Sai Cheemalapati

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

[diff] [blame^]

759

"mediaUpload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for media support using

760

# Bytestream, add instead

Jon Wayne Parrott

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

[diff] [blame]

761

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

Sai Cheemalapati

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

[diff] [blame^]

762

# configuration for Bytestream methods.

763

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

764

# your configuration for Bytestream methods.

Jon Wayne Parrott

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

[diff] [blame]

765

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

Sai Cheemalapati

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

[diff] [blame^]

766

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

767

#

768

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

Jon Wayne Parrott

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

[diff] [blame]

769

},

Sai Cheemalapati

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

[diff] [blame^]

770

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

771

#

772

# Refer to selector for syntax details.

Jon Wayne Parrott

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

[diff] [blame]

773

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

774

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

775

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

776

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

777

# at the top-level of response message type.

778

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

779

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

780

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

Sai Cheemalapati

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

[diff] [blame^]

781

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

782

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

783

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

784

},

Jon Wayne Parrott

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

[diff] [blame]

785

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

},

],

},

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

790

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

791

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

792

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

793

# which cannot be resolved against the associated IDL files.

794

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

795

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

796

{ # Method represents a method of an api.

797

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

798

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

799

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

800

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

801

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

802

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

803

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

804

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

805

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

806

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

807

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

808

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

809

# `"google.api.http"`.

810

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

811

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

812

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

813

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

814

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

},

},

],

},

],

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

821

# message.

822

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

823

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

824

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

825

},

826

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

827

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

828

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

829

# and options are inherited as follows:

830

#

831

# - If after comment and whitespace stripping, the documentation

832

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

833

# from the original method.

834

#

835

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

836

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

837

# inherited.

838

#

839

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

840

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

841

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

842

#

843

# Example of a simple mixin:

844

#

845

# package google.acl.v1;

846

# service AccessControl {

847

# // Get the underlying ACL object.

848

# rpc GetAcl(GetAclRequest) returns (Acl) {

849

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

# }

# }

#

# package google.storage.v2;

854

# service Storage {

855

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

856

#

857

# // Get a data record.

858

# rpc GetData(GetDataRequest) returns (Data) {

859

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

# }

# }

#

# Example of a mixin configuration:

864

#

865

# apis:

866

# - name: google.storage.v2.Storage

867

# mixins:

868

# - name: google.acl.v1.AccessControl

869

#

870

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

871

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

872

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

873

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

874

# documentation and annotations as follows:

875

#

876

# service Storage {

877

# // Get the underlying ACL object.

878

# rpc GetAcl(GetAclRequest) returns (Acl) {

879

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

# }

# ...

# }

#

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

885

#

886

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

887

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

888

#

889

# apis:

890

# - name: google.storage.v2.Storage

891

# mixins:

892

# - name: google.acl.v1.AccessControl

893

# root: acls

894

#

895

# This implies the following inherited HTTP annotation:

896

#

897

# service Storage {

898

# // Get the underlying ACL object.

899

# rpc GetAcl(GetAclRequest) returns (Acl) {

900

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

# }

# ...

# }

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

905

# are rooted.

906

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

907

},

908

],

909

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

910

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

911

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

912

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

913

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

914

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

915

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

916

# provided here.

917

#

918

# The versioning schema uses [semantic

919

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

920

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

921

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

922

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

923

# chosen based on the product plan.

924

#

925

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

926

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

927

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

928

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

929

# experimental, none-GA apis.

930

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

931

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

932

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

933

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

934

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

935

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

936

# `"google.api.http"`.

937

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

938

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

939

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

940

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

941

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

},

},

],

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

946

# followed by the api's simple name.

947

},

948

],

949

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

950

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

958

# - google.foo.v1.AnotherError

959

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

960

#

961

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

962

{ # A custom error rule.

963

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

964

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

965

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

966

#

967

# Refer to selector for syntax details.

968

},

969

],

970

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

"A String",

],

},

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

975

# elements. Restrictions are specified using visibility labels

976

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

977

#

978

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

979

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

980

# elements, plus any unrestricted elements.

981

#

982

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

983

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

990

# restriction: TRUSTED_TESTER

991

# - selector: google.calendar.Calendar.Delegate

992

# restriction: GOOGLE_INTERNAL

993

#

994

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

995

# EnhancedSearch and Delegate.

996

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

997

#

998

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

999

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

1000

# element.

Sai Cheemalapati

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

[diff] [blame]

1001

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

1002

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

Jon Wayne Parrott

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

[diff] [blame]

1003

#

1004

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

1005

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1012

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1013

#

1014

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1015

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

1016

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

1017

#

1018

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

1023

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

1024

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

1025

# existing data unusable.

Jon Wayne Parrott

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

[diff] [blame]

1026

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

1027

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

Sai Cheemalapati

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

[diff] [blame^]

1028

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

1029

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

1030

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

1031

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

1032

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

1033

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

1034

#

1035

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

Jon Wayne Parrott

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

[diff] [blame]

1036

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

1037

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

Jon Wayne Parrott

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

[diff] [blame]

1038

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

1039

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

Jon Wayne Parrott

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

[diff] [blame]

1040

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

1041

# instance of this metric type. For example, the

1042

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

1043

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

1044

# you can look at latencies for successful responses or just

1045

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1046

{ # A description of a label.

1047

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

1048

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

1049

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

1050

},

1051

],

Jon Wayne Parrott

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

[diff] [blame]

1052

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

1053

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

Jon Wayne Parrott

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

[diff] [blame]

1054

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

1055

# grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1056

#

Jon Wayne Parrott

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

[diff] [blame]

1057

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

1058

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

Jon Wayne Parrott

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

[diff] [blame]

1059

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

1060

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

1061

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

1062

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

1063

#

1064

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

1079

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

1080

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

1081

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

1082

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

1083

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

1084

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

1085

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

1086

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

1087

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

1088

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

1089

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

1090

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

1091

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

1092

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

1093

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

1094

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

#

# **Grammar**

#

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

1099

#

1100

# The grammar also includes these connectors:

1101

#

1102

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

1103

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

1104

#

1105

# The grammar for a unit is as follows:

1106

#

1107

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

1108

#

1109

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1119

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

1120

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

1121

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

1122

# containing '{' or '}'.

Sai Cheemalapati

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

[diff] [blame^]

1123

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

1124

},

1125

],

1126

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

1127

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

1128

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

1129

# should be listed here by name. Example:

1130

#

1131

# enums:

1132

# - name: google.someapi.v1.SomeEnum

1133

{ # Enum type definition.

Sai Cheemalapati

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

[diff] [blame^]

1134

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

Jon Wayne Parrott

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

[diff] [blame]

1135

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

1136

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

1137

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

1138

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

1139

},

Jon Wayne Parrott

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

[diff] [blame]

1140

"options": [ # Protocol buffer options.

1141

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

1142

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1143

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

1144

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

1145

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

1146

# `"google.api.http"`.

1147

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

1148

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

1149

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

1150

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1151

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

},

},

],

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

Sai Cheemalapati

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

[diff] [blame^]

1156

"enumvalue": [ # Enum value definitions.

1157

{ # Enum value definition.

1158

"options": [ # Protocol buffer options.

1159

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

1160

# enumeration, etc.

1161

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

1162

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

1163

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

1164

# `"google.api.http"`.

1165

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

1166

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

1167

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

1168

# value using the google.protobuf.Int32Value type.

1169

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

},

},

],

"number": 42, # Enum value number.

1174

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

1175

},

1176

],

Jon Wayne Parrott

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

[diff] [blame]

1177

},

1178

],

1179

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

1180

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

1181

# automatically included. Messages which are not referenced but

1182

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

1183

# should be listed here by name. Example:

1184

#

1185

# types:

1186

# - name: google.protobuf.Int32

1187

{ # A protocol buffer message type.

1188

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

1189

"A String",

1190

],

1191

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

Jon Wayne Parrott

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

[diff] [blame]

1192

"fields": [ # The list of fields.

1193

{ # A single field of a message type.

1194

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

1195

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

1196

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

1197

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

1198

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

1199

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

1200

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

1201

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

1202

"number": 42, # The field number.

1203

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

1204

"options": [ # The protocol buffer options.

1205

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

1206

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1207

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

1208

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

1209

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

1210

# `"google.api.http"`.

1211

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

1212

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

1213

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

1214

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1215

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

},

},

],

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

1220

},

1221

],

Sai Cheemalapati

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

[diff] [blame^]

1222

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

1223

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

1224

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

1225

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

1226

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

1227

},

Jon Wayne Parrott

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

[diff] [blame]

1228

"options": [ # The protocol buffer options.

1229

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

1230

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1231

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

1232

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

1233

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

1234

# `"google.api.http"`.

1235

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

1236

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

1237

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

1238

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1239

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1245

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

Jon Wayne Parrott

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

[diff] [blame]

1246

#

1247

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

Sai Cheemalapati

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

[diff] [blame]

1248

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

1249

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

1250

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

Jon Wayne Parrott

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

[diff] [blame]

1251

#

1252

# monitored_resources:

1253

# - type: library.googleapis.com/branch

1254

# labels:

1255

# - key: /city

1256

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

1257

# - key: /name

1258

# description: The name of the branch.

1259

# logs:

Sai Cheemalapati

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

[diff] [blame]

1260

# - name: activity_history

Jon Wayne Parrott

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

[diff] [blame]

1261

# labels:

1262

# - key: /customer_id

Sai Cheemalapati

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

[diff] [blame]

1263

# - name: purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1264

# logging:

1265

# producer_destinations:

1266

# - monitored_resource: library.googleapis.com/branch

1267

# logs:

Sai Cheemalapati

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

[diff] [blame]

1268

# - activity_history

1269

# - purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1270

# consumer_destinations:

1271

# - monitored_resource: library.googleapis.com/branch

1272

# logs:

Sai Cheemalapati

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

[diff] [blame]

1273

# - activity_history

Jon Wayne Parrott

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

[diff] [blame]

1274

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

1275

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

1276

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

1277

# one producer destination.

1278

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

1279

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1280

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

1281

# Service.monitored_resources section.

1282

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

1283

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

1284

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

1285

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

1291

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

1292

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

1293

# one consumer destination.

1294

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

1295

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1296

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

1297

# Service.monitored_resources section.

1298

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

1299

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

1300

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

1301

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

1308

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

1309

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

1310

#

1311

# Example:

1312

# <pre><code>documentation:

1313

# summary: >

1314

# The Google Calendar API gives access

1315

# to most calendar features.

1316

# pages:

1317

# - name: Overview

1318

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

1319

# - name: Tutorial

1320

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

1321

# subpages;

1322

# - name: Java

1323

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

1324

# rules:

1325

# - selector: google.calendar.Calendar.Get

1326

# description: >

1327

# ...

1328

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1333

# standard markdown features, definition lists, tables and fenced

1334

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

1335

# interpreted relative to the section nesting of the context where

1336

# a documentation fragment is embedded.

1337

#

1338

# Documentation from the IDL is merged with documentation defined

1339

# via the config at normalization time, where documentation provided

1340

# by config rules overrides IDL provided.

1341

#

1342

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

1343

# in documentation text.

1344

#

1345

# In order to reference a proto element, the following

1346

# notation can be used:

1347

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

1348

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

1349

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

1350

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

1351

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

1352

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

1353

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

1354

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

1355

# A few directives are available in documentation. Note that

1356

# directives must appear on a single line to be properly

1357

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

1358

# an external source:

1359

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

1360

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

1361

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

1362

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

1363

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

1364

# The directive `suppress_warning` does not directly affect documentation

1365

# and is documented together with service config validation.

1366

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

1367

#

1368

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

1369

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

1370

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

1371

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

1372

# element is marked as `deprecated`.

1373

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

1374

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

1375

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

1376

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

1377

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

1378

# is used.

1379

},

1380

],

Sai Cheemalapati

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

[diff] [blame^]

1381

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

Jon Wayne Parrott

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

[diff] [blame]

1382

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

1383

# plain text.

1384

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

1385

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

1386

# nested documentation set structure.

1387

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

1388

# to include content from a Markdown file.

1389

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

1390

# honored in the generated docset.

1391

# Object with schema name: Page

1392

],

1393

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

1394

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

1395

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

1396

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

1397

# documentation. For example:

1398

# <pre><code>pages:

1399

# - name: Tutorial

1400

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

1401

# subpages:

1402

# - name: Java

1403

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

1404

# </code></pre>

1405

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

1406

# `Java`.

1407

},

1408

],

Sai Cheemalapati

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

[diff] [blame^]

1409

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

1410

# <pre><code>documentation:

1411

# summary: ...

1412

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

1413

# </code></pre>

1414

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

1415

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1420

# </code></pre>

1421

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

1422

},

1423

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

1424

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

1425

{

1426

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

1427

},

1428

],

Jon Wayne Parrott

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

[diff] [blame]

1429

},

1430

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

1431

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

1432

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

1433

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

1434

# to define system APIs in ESF.

1435

{ # A protocol buffer message type.

1436

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

1437

"A String",

1438

],

1439

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

Jon Wayne Parrott

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

[diff] [blame]

1440

"fields": [ # The list of fields.

1441

{ # A single field of a message type.

1442

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

1443

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

1444

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

1445

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

1446

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

1447

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

1448

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

1449

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

1450

"number": 42, # The field number.

1451

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

1452

"options": [ # The protocol buffer options.

1453

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

1454

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1455

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

1456

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

1457

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

1458

# `"google.api.http"`.

1459

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

1460

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

1461

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

1462

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1463

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

},

},

],

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

1468

},

1469

],

Sai Cheemalapati

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

[diff] [blame^]

1470

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

1471

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

1472

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

1473

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

1474

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

1475

},

Jon Wayne Parrott

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

[diff] [blame]

1476

"options": [ # The protocol buffer options.

1477

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

1478

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame]

1479

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

1480

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

1481

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

1482

# `"google.api.http"`.

1483

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

1484

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

1485

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

1486

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1487

"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

1502

# - google.rpc.context.OriginContext

1503

#

1504

# The above specifies that all methods in the API request

1505

# `google.rpc.context.ProjectContext` and

1506

# `google.rpc.context.OriginContext`.

1507

#

1508

# Available context types are defined in package

1509

# `google.rpc.context`.

1510

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

1511

#

1512

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

1513

{ # A context rule provides information about the context for an individual API

1514

# element.

1515

"provided": [ # A list of full type names of provided contexts.

1516

"A String",

1517

],

1518

"requested": [ # A list of full type names of requested contexts.

1519

"A String",

1520

],

1521

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

1522

#

1523

# Refer to selector for syntax details.

1524

},

1525

],

1526

},

Sai Cheemalapati

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

[diff] [blame^]

1527

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

Sai Cheemalapati

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

[diff] [blame]

1528

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

1529

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

1530

# defined APIs.

1531

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

1532

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

1533

# same service configuration, such as quota configuration and monitoring

1534

# configuration.

1535

#

1536

# Example service configuration:

1537

#

1538

# name: library-example.googleapis.com

1539

# endpoints:

1540

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

1541

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

1542

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

1543

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

1544

# # allowed to proceed.

1545

# - name: library-example.googleapis.com

Sai Cheemalapati

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

[diff] [blame]

1546

# allow_cors: true

Sai Cheemalapati

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

[diff] [blame]

1547

"allowCors": True or False, # Allowing

1548

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

1549

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

1550

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

1551

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

1552

# allowed to proceed.

1553

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

1554

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

1555

# alias.

1556

#

1557

# Additional names that this endpoint will be hosted on.

1558

"A String",

1559

],

1560

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

1561

"A String",

1562

],

1563

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

1564

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Sai Cheemalapati

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

[diff] [blame^]

1569

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

1570

# only be used by whitelisted users.

1571

"authorization": { # Configuration of authorization. # Authorization configuration.

1572

#

1573

# This section determines the authorization provider, if unspecified, then no

1574

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

1581

"provider": "A String", # The name of the authorization provider, such as

1582

# firebaserules.googleapis.com.

1583

},

1584

},

Jon Wayne Parrott

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

[diff] [blame]

1585

}

1586

1587

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1594

Sai Cheemalapati

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

[diff] [blame]

1595

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

1596

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

1597

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

1598

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

1599

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

1604

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

1605

# name: calendar.googleapis.com

1606

# title: Google Calendar API

1607

# apis:

Sai Cheemalapati

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

[diff] [blame]

1608

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame]

1609

# authentication:

1610

# providers:

1611

# - id: google_calendar_auth

1612

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

1613

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

Jon Wayne Parrott

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

[diff] [blame]

1614

# rules:

Jon Wayne Parrott

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

[diff] [blame]

1615

# - selector: "*"

1616

# requirements:

1617

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

1618

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

1619

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

1620

# monitoring, etc.

1621

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

1622

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

1623

},

1624

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

1625

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

1626

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

1627

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

1628

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

1629

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

1630

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

1631

#

1632

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

1633

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

1634

# by the API.

1635

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

1636

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

1637

# The maximum length of this value is 256 characters.

1638

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

1639

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

1640

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

1641

{ # A description of a label.

1642

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

1643

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

1644

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

1645

},

1646

],

1647

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

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

1648

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

1649

# without any article or other determiners. For example,

1650

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

1651

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

1652

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

1653

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

1654

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

1655

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

1656

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

Sai Cheemalapati

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

[diff] [blame^]

1657

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

1658

# be used in documentation.

Jon Wayne Parrott

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

[diff] [blame]

1659

},

1660

],

1661

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

1662

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

1663

#

1664

# - name: library.googleapis.com/activity_history

1665

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

1666

# display_name: Activity

1667

# labels:

1668

# - key: /customer_id

1669

# description: Identifier of a library customer

1670

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

1671

# Runtime requests that contain labels not specified here are

1672

# considered invalid.

1673

{ # A description of a label.

1674

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

1675

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

1676

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

1677

},

1678

],

1679

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

1680

# the user interface and should be concise.

Jon Wayne Parrott

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

[diff] [blame]

1681

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

1682

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

1683

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

1684

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

Sai Cheemalapati

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

[diff] [blame^]

1685

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

1686

# the documentation and can contain details.

Jon Wayne Parrott

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

[diff] [blame]

1687

},

1688

],

Sai Cheemalapati

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

[diff] [blame^]

1689

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

1690

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

1691

# generate one instead.

Jon Wayne Parrott

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

[diff] [blame]

1692

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

1693

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

1694

#

1695

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

1696

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

1697

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

1698

#

1699

# Refer to selector for syntax details.

1700

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

1701

# default depends on the deployment context.

1702

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

1703

},

1704

],

1705

},

Sai Cheemalapati

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

[diff] [blame]

1706

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

Jon Wayne Parrott

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

[diff] [blame]

1707

#

1708

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

1709

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

1710

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

1711

# to both producer and consumer projects, whereas the

1712

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

1713

# consumer project.

1714

#

1715

# monitored_resources:

1716

# - type: library.googleapis.com/branch

1717

# labels:

1718

# - key: /city

1719

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

1720

# - key: /name

1721

# description: The name of the branch.

1722

# metrics:

1723

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1728

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1733

# monitoring:

1734

# producer_destinations:

1735

# - monitored_resource: library.googleapis.com/branch

1736

# metrics:

1737

# - library.googleapis.com/book/returned_count

1738

# consumer_destinations:

1739

# - monitored_resource: library.googleapis.com/branch

1740

# metrics:

1741

# - library.googleapis.com/book/returned_count

1742

# - library.googleapis.com/book/overdue_count

1743

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

1744

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

1745

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

1746

# one producer destination.

1747

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

1748

# or the consumer project).

1749

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

1750

# Service.monitored_resources section.

1751

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

1752

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

"A String",

],

},

],

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

1758

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

1759

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

1760

# one consumer destination.

1761

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

1762

# or the consumer project).

1763

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

1764

# Service.monitored_resources section.

1765

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

1766

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

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame^]

1772

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

1773

#

1774

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

1775

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

1776

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

1777

# change the names of the system parameters.

1778

"rules": [ # Define system parameters.

1779

#

1780

# The parameters defined here will override the default parameters

1781

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

1782

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

1783

# and names is implementation-dependent.

1784

#

1785

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1793

#

1794

#

1795

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1800

# parameters:

1801

# - name: api_key

1802

# http_header: Api-Key1

1803

# - name: api_key

1804

# http_header: Api-Key2

1805

#

1806

# **NOTE:** All service configuration rules follow "last one wins" order.

1807

{ # Define a system parameter rule mapping system parameter definitions to

1808

# methods.

1809

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

1810

# For a given method call, only one of them should be used. If multiple

1811

# names are used the behavior is implementation-dependent.

1812

# If none of the specified names are present the behavior is

1813

# parameter-dependent.

1814

{ # Define a parameter's name and location. The parameter may be passed as either

1815

# an HTTP header or a URL query parameter, and if both are passed the behavior

1816

# is implementation-dependent.

1817

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

1818

# sensitive.

1819

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

1820

# insensitive.

1821

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

1822

},

1823

],

1824

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1825

# methods in all APIs.

1826

#

1827

# Refer to selector for syntax details.

1828

},

1829

],

1830

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1831

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

1832

#

1833

# Example for an API targeted for external use:

1834

#

1835

# name: calendar.googleapis.com

1836

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1837

# providers:

1838

# - id: google_calendar_auth

1839

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

1840

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1841

# rules:

1842

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1843

# requirements:

1844

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1845

"rules": [ # A list of authentication rules that apply to individual API methods.

1846

#

1847

# **NOTE:** All service configuration rules follow "last one wins" order.

1848

{ # Authentication rules for the service.

1849

#

1850

# By default, if a method has any authentication requirements, every request

1851

# must include a valid credential matching one of the requirements.

1852

# It's an error to include more than one kind of credential in a single

1853

# request.

1854

#

1855

# If a method doesn't have any auth requirements, request credentials will be

1856

# ignored.

1857

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

1858

# there are scopes defined for "Read-only access to Google Calendar" and

1859

# "Access to Cloud Platform". Users can consent to a scope for an application,

1860

# giving it permission to access that data on their behalf.

1861

#

1862

# OAuth scope specifications should be fairly coarse grained; a user will need

1863

# to see and understand the text description of what your scope means.

1864

#

1865

# In most cases: use one or at most two OAuth scopes for an entire family of

1866

# products. If your product has multiple APIs, you should probably be sharing

1867

# the OAuth scope across all of those APIs.

1868

#

1869

# When you need finer grained OAuth consent screens: talk with your product

1870

# management about how developers will use them in practice.

1871

#

1872

# Please note that even though each of the canonical scopes is enough for a

1873

# request to be accepted and passed to the backend, a request can still fail

1874

# due to the backend requiring additional scopes or permissions.

1875

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

1876

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

1881

# https://www.googleapis.com/auth/calendar.read

1882

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

1883

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

1884

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

1885

#

1886

# For requests without credentials, if the service control environment is

1887

# specified, each incoming request **must** be associated with a service

1888

# consumer. This can be done by passing an API key that belongs to a consumer

1889

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1890

"requirements": [ # Requirements for additional authentication providers.

1891

{ # User-defined authentication requirements, including support for

1892

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

1893

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1898

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

1899

# implemented and accepted in all the runtime components.

1900

#

1901

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1902

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

1903

# that are allowed to access. A JWT containing any of these audiences will

1904

# be accepted. When this setting is absent, only JWTs with audience

1905

# "https://Service_name/API_name"

1906

# will be accepted. For example, if no audiences are in the setting,

1907

# LibraryService API will only accept JWTs with the following audience

1908

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1913

# bookstore_web.apps.googleusercontent.com

1914

},

1915

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1916

"selector": "A String", # Selects the methods to which this rule applies.

1917

#

1918

# Refer to selector for syntax details.

1919

},

1920

],

1921

"providers": [ # Defines a set of authentication providers that a service supports.

1922

{ # Configuration for an anthentication provider, including support for

1923

# [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]

1924

"audiences": "A String", # The list of JWT

1925

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

1926

# that are allowed to access. A JWT containing any of these audiences will

1927

# be accepted. When this setting is absent, only JWTs with audience

1928

# "https://Service_name/API_name"

1929

# will be accepted. For example, if no audiences are in the setting,

1930

# LibraryService API will only accept JWTs with the following audience

1931

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1936

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

1937

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

1938

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

1939

# Optional if the key set document:

1940

# - can be retrieved from

1941

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

1942

# of the issuer.

1943

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

1944

#

1945

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1946

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

1947

# `AuthRequirement.provider_id`.

1948

#

1949

# Example: "bookstore_auth".

1950

"issuer": "A String", # Identifies the principal that issued the JWT. See

1951

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

1952

# Usually a URL or an email address.

1953

#

1954

# Example: https://securetoken.google.com

1955

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

1960

"rules": [ # A list of usage rules that apply to individual API methods.

1961

#

1962

# **NOTE:** All service configuration rules follow "last one wins" order.

1963

{ # Usage configuration rules for the service.

1964

#

1965

# NOTE: Under development.

1966

#

1967

#

1968

# Use this rule to configure unregistered calls for the service. Unregistered

1969

# calls are calls that do not contain consumer project identity.

1970

# (Example: calls that do not contain an API key).

1971

# By default, API methods do not allow unregistered calls, and each method call

1972

# must be identified by a consumer project identity. Use this rule to

1973

# allow/disallow unregistered calls.

1974

#

1975

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1981

#

1982

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

1987

# allow_unregistered_calls: true

1988

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1989

# methods in all APIs.

1990

#

1991

# Refer to selector for syntax details.

1992

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

1993

},

1994

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

1995

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

1996

# service producer.

1997

#

1998

# Google Service Management currently only supports

1999

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

2000

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

2001

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

2002

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2003

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

2004

# service. Each requirement is of the form <service.name>/<requirement-id>;

2005

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

2010

# influence interpretation of the configuration, for example, to

2011

# determine defaults. This is documented together with applicable

2012

# options. The current default for the config version itself is `3`.

2013

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

2014

# Members of this project can manage the service configuration,

2015

# manage consumption of the service, etc.

2016

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

2017

# HttpRule, each specifying the mapping of an RPC method

2018

# to one or more HTTP REST API methods.

2019

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

2020

#

2021

# **NOTE:** All service configuration rules follow "last one wins" order.

2022

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

2023

# REST APIs. The mapping determines what portions of the request

2024

# message are populated from the path, query parameters, or body of

2025

# the HTTP request. The mapping is typically specified as an

2026

# `google.api.http` annotation, see "google/api/annotations.proto"

2027

# for details.

2028

#

2029

# The mapping consists of a field specifying the path template and

2030

# method kind. The path template can refer to fields in the request

2031

# message, as in the example below which describes a REST GET

2032

# operation on a resource collection of messages:

2033

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2034

#

2035

# service Messaging {

2036

# rpc GetMessage(GetMessageRequest) returns (Message) {

2037

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

2038

# }

2039

# }

2040

# message GetMessageRequest {

2041

# message SubMessage {

2042

# string subfield = 1;

2043

# }

2044

# string message_id = 1; // mapped to the URL

2045

# SubMessage sub = 2; // `sub.subfield` is url-mapped

2046

# }

2047

# message Message {

2048

# string text = 1; // content of the resource

2049

# }

2050

#

2051

# The same http annotation can alternatively be expressed inside the

2052

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

2057

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2058

#

2059

# This definition enables an automatic, bidrectional mapping of HTTP

2060

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

2065

#

2066

# In general, not only fields but also field paths can be referenced

2067

# from a path pattern. Fields mapped to the path pattern cannot be

2068

# repeated and must have a primitive (non-message) type.

2069

#

2070

# Any fields in the request message which are not bound by the path

2071

# pattern automatically become (optional) HTTP query

2072

# parameters. Assume the following definition of the request message:

2073

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2074

#

2075

# message GetMessageRequest {

2076

# message SubMessage {

2077

# string subfield = 1;

2078

# }

2079

# string message_id = 1; // mapped to the URL

2080

# int64 revision = 2; // becomes a parameter

2081

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

2082

# }

2083

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2084

#

2085

# 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"))`

2090

#

2091

# Note that fields which are mapped to HTTP parameters must have a

2092

# primitive type or a repeated primitive type. Message types are not

2093

# allowed. In the case of a repeated type, the parameter can be

2094

# repeated in the URL, as in `...?param=A&param=B`.

2095

#

2096

# For HTTP method kinds which allow a request body, the `body` field

2097

# specifies the mapping. Consider a REST update method on the

2098

# message resource collection:

2099

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2100

#

2101

# service Messaging {

2102

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2103

# option (google.api.http) = {

2104

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2110

# string message_id = 1; // mapped to the URL

2111

# Message message = 2; // mapped to the body

2112

# }

2113

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2114

#

2115

# The following HTTP JSON to RPC mapping is enabled, where the

2116

# representation of the JSON in the request body is determined by

2117

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

2122

#

2123

# The special name `*` can be used in the body mapping to define that

2124

# every field not bound by the path template should be mapped to the

2125

# request body. This enables the following alternative definition of

2126

# the update method:

2127

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2128

# service Messaging {

2129

# rpc UpdateMessage(Message) returns (Message) {

2130

# option (google.api.http) = {

2131

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

2138

# string text = 2;

2139

# }

2140

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2141

#

2142

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

2147

#

2148

# Note that when using `*` in the body mapping, it is not possible to

2149

# have HTTP parameters, as all fields not bound by the path end in

2150

# the body. This makes this option more rarely used in practice of

2151

# defining REST APIs. The common usage of `*` is in custom methods

2152

# which don't use the URL at all for transferring data.

2153

#

2154

# It is possible to define multiple HTTP methods for one RPC by using

2155

# the `additional_bindings` option. Example:

2156

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2157

# service Messaging {

2158

# rpc GetMessage(GetMessageRequest) returns (Message) {

2159

# option (google.api.http) = {

2160

# get: "/v1/messages/{message_id}"

2161

# additional_bindings {

2162

# get: "/v1/users/{user_id}/messages/{message_id}"

2163

# }

2164

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2165

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2166

# }

2167

# message GetMessageRequest {

2168

# string message_id = 1;

2169

# string user_id = 2;

2170

# }

2171

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2172

#

2173

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

2179

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

2180

#

2181

# # Rules for HTTP mapping

2182

#

2183

# The rules for mapping HTTP path, query parameters, and body fields

2184

# to the request message are as follows:

2185

#

2186

# 1. The `body` field specifies either `*` or a field path, or is

2187

# omitted. If omitted, it assumes there is no HTTP body.

2188

# 2. Leaf fields (recursive expansion of nested messages in the

2189

# request) can be classified into three types:

2190

# (a) Matched in the URL template.

2191

# (b) Covered by body (if body is `*`, everything except (a) fields;

2192

# else everything under the body field)

2193

# (c) All other fields.

2194

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

2195

# 4. Any body sent with an HTTP request can contain only (b) fields.

2196

#

2197

# The syntax of the path template is as follows:

2198

#

2199

# Template = "/" Segments [ Verb ] ;

2200

# Segments = Segment { "/" Segment } ;

2201

# Segment = "*" | "**" | LITERAL | Variable ;

2202

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2203

# FieldPath = IDENT { "." IDENT } ;

2204

# Verb = ":" LITERAL ;

2205

#

2206

# The syntax `*` matches a single path segment. It follows the semantics of

2207

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2208

# Expansion.

2209

#

2210

# The syntax `**` matches zero or more path segments. It follows the semantics

2211

# 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]

2212

# 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]

2213

#

2214

# The syntax `LITERAL` matches literal text in the URL path.

2215

#

2216

# The syntax `Variable` matches the entire path as specified by its template;

2217

# this nested template must not contain further variables. If a variable

2218

# matches a single path segment, its template may be omitted, e.g. `{var}`

2219

# is equivalent to `{var=*}`.

2220

#

2221

# NOTE: the field paths in variables and in the `body` must not refer to

2222

# repeated fields or map fields.

2223

#

2224

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2225

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2226

# a given URL path rule. The wild-card rule is useful for services that provide

2227

# content to Web (HTML) clients.

2228

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2229

# `*` for mapping all fields not captured by the path pattern to the HTTP

2230

# 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]

2231

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2232

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2233

"mediaDownload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for bytestream methods.

2234

# For media support, add instead [][google.bytestream.RestByteStream] as an

2235

# API to your configuration.

2236

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

2237

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2238

"enabled": True or False, # Whether download is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2239

"downloadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

2240

#

2241

# Specify name of the download service if one is used for download.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2242

},

2243

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2244

# not contain an `additional_bindings` field themselves (that is,

2245

# the nesting may only be one level deep).

2246

# Object with schema name: HttpRule

2247

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2248

"mediaUpload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for media support using

2249

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2250

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2251

# configuration for Bytestream methods.

2252

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

2253

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2254

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2255

"uploadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

2256

#

2257

# Specify name of the upload service if one is used for upload.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2258

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2259

"selector": "A String", # Selects methods to which this rule applies.

2260

#

2261

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2262

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2263

# response. Other response fields are ignored. This field is optional. When

2264

# not set, the response message will be used as HTTP body of response.

2265

# NOTE: the referred field must be not a repeated field and must be present

2266

# at the top-level of response message type.

2267

"put": "A String", # Used for updating a resource.

2268

"patch": "A String", # Used for updating a resource.

2269

"post": "A String", # Used for creating a resource.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2270

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2271

"path": "A String", # The path matched by this custom verb.

2272

"kind": "A String", # The name of this custom HTTP verb.

2273

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2274

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2279

# of the google.protobuf.Api needs to be provided by the configuration

2280

# author, as the remaining fields will be derived from the IDL during the

2281

# normalization process. It is an error to specify an API interface here

2282

# which cannot be resolved against the associated IDL files.

2283

{ # Api is a light-weight descriptor for a protocol buffer service.

2284

"methods": [ # The methods of this api, in unspecified order.

2285

{ # Method represents a method of an api.

2286

"name": "A String", # The simple name of this method.

2287

"requestStreaming": True or False, # If true, the request is streamed.

2288

"responseTypeUrl": "A String", # The URL of the output message type.

2289

"requestTypeUrl": "A String", # A URL of the input message type.

2290

"responseStreaming": True or False, # If true, the response is streamed.

2291

"syntax": "A String", # The source syntax of this method.

2292

"options": [ # Any metadata attached to the method.

2293

{ # A protocol buffer option, which can be attached to a message, field,

2294

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2295

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2296

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2297

# For custom options, it should be the fully-qualified name. For example,

2298

# `"google.api.http"`.

2299

"value": { # The option's value packed in an Any message. If the value is a primitive,

2300

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2301

# should be used. If the value is an enum, it should be stored as an int32

2302

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2303

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

2310

# message.

2311

# protobuf element, like the file in which it is defined.

2312

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2313

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2314

},

2315

"mixins": [ # Included APIs. See Mixin.

2316

{ # Declares an API to be included in this API. The including API must

2317

# redeclare all the methods from the included API, but documentation

2318

# and options are inherited as follows:

2319

#

2320

# - If after comment and whitespace stripping, the documentation

2321

# string of the redeclared method is empty, it will be inherited

2322

# from the original method.

2323

#

2324

# - Each annotation belonging to the service config (http,

2325

# visibility) which is not set in the redeclared method will be

2326

# inherited.

2327

#

2328

# - If an http annotation is inherited, the path pattern will be

2329

# modified as follows. Any version prefix will be replaced by the

2330

# version of the including API plus the root path if specified.

2331

#

2332

# Example of a simple mixin:

2333

#

2334

# package google.acl.v1;

2335

# service AccessControl {

2336

# // Get the underlying ACL object.

2337

# rpc GetAcl(GetAclRequest) returns (Acl) {

2338

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2343

# service Storage {

2344

# // rpc GetAcl(GetAclRequest) returns (Acl);

2345

#

2346

# // Get a data record.

2347

# rpc GetData(GetDataRequest) returns (Data) {

2348

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2353

#

2354

# apis:

2355

# - name: google.storage.v2.Storage

2356

# mixins:

2357

# - name: google.acl.v1.AccessControl

2358

#

2359

# The mixin construct implies that all methods in `AccessControl` are

2360

# also declared with same name and request/response types in

2361

# `Storage`. A documentation generator or annotation processor will

2362

# see the effective `Storage.GetAcl` method after inherting

2363

# documentation and annotations as follows:

2364

#

2365

# service Storage {

2366

# // Get the underlying ACL object.

2367

# rpc GetAcl(GetAclRequest) returns (Acl) {

2368

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2374

#

2375

# If the `root` field in the mixin is specified, it should be a

2376

# relative path under which inherited HTTP paths are placed. Example:

2377

#

2378

# apis:

2379

# - name: google.storage.v2.Storage

2380

# mixins:

2381

# - name: google.acl.v1.AccessControl

2382

# root: acls

2383

#

2384

# This implies the following inherited HTTP annotation:

2385

#

2386

# service Storage {

2387

# // Get the underlying ACL object.

2388

# rpc GetAcl(GetAclRequest) returns (Acl) {

2389

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2394

# are rooted.

2395

"name": "A String", # The fully qualified name of the API which is included.

2396

},

2397

],

2398

"syntax": "A String", # The source syntax of the service.

2399

"version": "A String", # A version string for this api. If specified, must have the form

2400

# `major-version.minor-version`, as in `1.10`. If the minor version

2401

# is omitted, it defaults to zero. If the entire version field is

2402

# empty, the major version is derived from the package name, as

2403

# outlined below. If the field is not empty, the version in the

2404

# package name will be verified to be consistent with what is

2405

# provided here.

2406

#

2407

# The versioning schema uses [semantic

2408

# versioning](http://semver.org) where the major version number

2409

# indicates a breaking change and the minor version an additive,

2410

# non-breaking change. Both version numbers are signals to users

2411

# what to expect from different versions, and should be carefully

2412

# chosen based on the product plan.

2413

#

2414

# The major version is also reflected in the package name of the

2415

# API, which must end in `v<major-version>`, as in

2416

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2417

# be omitted. Zero major versions must only be used for

2418

# experimental, none-GA apis.

2419

"options": [ # Any metadata attached to the API.

2420

{ # A protocol buffer option, which can be attached to a message, field,

2421

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2422

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2423

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2424

# For custom options, it should be the fully-qualified name. For example,

2425

# `"google.api.http"`.

2426

"value": { # The option's value packed in an Any message. If the value is a primitive,

2427

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2428

# should be used. If the value is an enum, it should be stored as an int32

2429

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2430

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

2435

# followed by the api's simple name.

2436

},

2437

],

2438

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2439

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2447

# - google.foo.v1.AnotherError

2448

"rules": [ # The list of custom error rules that apply to individual API messages.

2449

#

2450

# **NOTE:** All service configuration rules follow "last one wins" order.

2451

{ # A custom error rule.

2452

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2453

# objects of this type will be filtered when they appear in error payload.

2454

"selector": "A String", # Selects messages to which this rule applies.

2455

#

2456

# Refer to selector for syntax details.

2457

},

2458

],

2459

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

2464

# elements. Restrictions are specified using visibility labels

2465

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2466

#

2467

# Users and projects can have access to more than one visibility label. The

2468

# effective visibility for multiple labels is the union of each label's

2469

# elements, plus any unrestricted elements.

2470

#

2471

# If an element and its parents have no restrictions, visibility is

2472

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2479

# restriction: TRUSTED_TESTER

2480

# - selector: google.calendar.Calendar.Delegate

2481

# restriction: GOOGLE_INTERNAL

2482

#

2483

# Here, all methods are publicly visible except for the restricted methods

2484

# EnhancedSearch and Delegate.

2485

"rules": [ # A list of visibility rules that apply to individual API elements.

2486

#

2487

# **NOTE:** All service configuration rules follow "last one wins" order.

2488

{ # A visibility rule provides visibility configuration for an individual API

2489

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2490

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

2491

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2492

#

2493

# If a rule has multiple labels, removing one of the labels but not all of

2494

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2501

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2502

#

2503

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2504

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2505

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2506

#

2507

# 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]

2512

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2513

# deleting or altering it stops data collection and makes the metric type's

2514

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2515

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2516

# Use sentence case without an ending period, for example "Request count".

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2517

"name": "A String", # The resource name of the metric descriptor. Depending on the

2518

# implementation, the name typically includes: (1) the parent resource name

2519

# that defines the scope of the metric type or of its data; and (2) the

2520

# metric's URL-encoded type, which also appears in the `type` field of this

2521

# descriptor. For example, following is the resource name of a custom

2522

# metric within the GCP project `my-project-id`:

2523

#

2524

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2525

"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]

2526

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2527

"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]

2528

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2529

"labels": [ # The set of labels that can be used to describe a specific

2530

# instance of this metric type. For example, the

2531

# `appengine.googleapis.com/http/server/response_latencies` metric

2532

# type has a label for the HTTP response code, `response_code`, so

2533

# you can look at latencies for successful responses or just

2534

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2535

{ # A description of a label.

2536

"valueType": "A String", # The type of data that can be assigned to the label.

2537

"description": "A String", # A human-readable description for the label.

2538

"key": "A String", # The label key.

2539

},

2540

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2541

"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^]

2542

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2543

# `custom.googleapis.com`. Metric types should use a natural hierarchical

2544

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2545

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2546

# "custom.googleapis.com/invoice/paid/amount"

2547

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2548

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2549

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2550

# supported units are a subset of [The Unified Code for Units of

2551

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2552

#

2553

# **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)

2568

# * `P` peta (10**15)

2569

# * `E` exa (10**18)

2570

# * `Z` zetta (10**21)

2571

# * `Y` yotta (10**24)

2572

# * `m` milli (10**-3)

2573

# * `u` micro (10**-6)

2574

# * `n` nano (10**-9)

2575

# * `p` pico (10**-12)

2576

# * `f` femto (10**-15)

2577

# * `a` atto (10**-18)

2578

# * `z` zepto (10**-21)

2579

# * `y` yocto (10**-24)

2580

# * `Ki` kibi (2**10)

2581

# * `Mi` mebi (2**20)

2582

# * `Gi` gibi (2**30)

2583

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2588

#

2589

# The grammar also includes these connectors:

2590

#

2591

# * `/` division (as an infix operator, e.g. `1/s`).

2592

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2593

#

2594

# The grammar for a unit is as follows:

2595

#

2596

# Expression = Component { "." Component } { "/" Component } ;

2597

#

2598

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2608

# equivalent to `1` if it is used alone. For examples,

2609

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2610

# * `NAME` is a sequence of non-blank printable ASCII characters not

2611

# containing '{' or '}'.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2612

"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]

2613

},

2614

],

2615

"enums": [ # A list of all enum types included in this API service. Enums

2616

# referenced directly or indirectly by the `apis` are automatically

2617

# included. Enums which are not referenced but shall be included

2618

# should be listed here by name. Example:

2619

#

2620

# enums:

2621

# - name: google.someapi.v1.SomeEnum

2622

{ # Enum type definition.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2623

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2624

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2625

# protobuf element, like the file in which it is defined.

2626

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2627

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2628

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2629

"options": [ # Protocol buffer options.

2630

{ # A protocol buffer option, which can be attached to a message, field,

2631

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2632

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2633

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2634

# For custom options, it should be the fully-qualified name. For example,

2635

# `"google.api.http"`.

2636

"value": { # The option's value packed in an Any message. If the value is a primitive,

2637

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2638

# should be used. If the value is an enum, it should be stored as an int32

2639

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2640

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2645

"enumvalue": [ # Enum value definitions.

2646

{ # Enum value definition.

2647

"options": [ # Protocol buffer options.

2648

{ # A protocol buffer option, which can be attached to a message, field,

2649

# enumeration, etc.

2650

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2651

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2652

# For custom options, it should be the fully-qualified name. For example,

2653

# `"google.api.http"`.

2654

"value": { # The option's value packed in an Any message. If the value is a primitive,

2655

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2656

# should be used. If the value is an enum, it should be stored as an int32

2657

# value using the google.protobuf.Int32Value type.

2658

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"number": 42, # Enum value number.

2663

"name": "A String", # Enum value name.

2664

},

2665

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2666

},

2667

],

2668

"types": [ # A list of all proto message types included in this API service.

2669

# Types referenced directly or indirectly by the `apis` are

2670

# automatically included. Messages which are not referenced but

2671

# shall be included, such as types used by the `google.protobuf.Any` type,

2672

# should be listed here by name. Example:

2673

#

2674

# types:

2675

# - name: google.protobuf.Int32

2676

{ # A protocol buffer message type.

2677

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2678

"A String",

2679

],

2680

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2681

"fields": [ # The list of fields.

2682

{ # A single field of a message type.

2683

"kind": "A String", # The field type.

2684

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2685

# types. The first type has index 1; zero means the type is not in the list.

2686

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2687

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2688

"name": "A String", # The field name.

2689

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2690

"jsonName": "A String", # The field JSON name.

2691

"number": 42, # The field number.

2692

"cardinality": "A String", # The field cardinality.

2693

"options": [ # The protocol buffer options.

2694

{ # A protocol buffer option, which can be attached to a message, field,

2695

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2696

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2697

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2698

# For custom options, it should be the fully-qualified name. For example,

2699

# `"google.api.http"`.

2700

"value": { # The option's value packed in an Any message. If the value is a primitive,

2701

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2702

# should be used. If the value is an enum, it should be stored as an int32

2703

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2704

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2709

},

2710

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2711

"syntax": "A String", # The source syntax.

2712

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2713

# protobuf element, like the file in which it is defined.

2714

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2715

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2716

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2717

"options": [ # The protocol buffer options.

2718

{ # A protocol buffer option, which can be attached to a message, field,

2719

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2720

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2721

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2722

# For custom options, it should be the fully-qualified name. For example,

2723

# `"google.api.http"`.

2724

"value": { # The option's value packed in an Any message. If the value is a primitive,

2725

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2726

# should be used. If the value is an enum, it should be stored as an int32

2727

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2728

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2734

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2735

#

2736

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2737

# producer and consumer projects. In the example, the `activity_history`

2738

# log is sent to both the producer and consumer projects, whereas the

2739

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2740

#

2741

# monitored_resources:

2742

# - type: library.googleapis.com/branch

2743

# labels:

2744

# - key: /city

2745

# description: The city where the library branch is located in.

2746

# - key: /name

2747

# description: The name of the branch.

2748

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2749

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2750

# labels:

2751

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2752

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2753

# logging:

2754

# producer_destinations:

2755

# - monitored_resource: library.googleapis.com/branch

2756

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2757

# - activity_history

2758

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2759

# consumer_destinations:

2760

# - monitored_resource: library.googleapis.com/branch

2761

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2762

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2763

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2764

# There can be multiple producer destinations, each one must have a

2765

# different monitored resource type. A log can be used in at most

2766

# one producer destination.

2767

{ # Configuration of a specific logging destination (the producer project

2768

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2769

"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]

2770

# Service.monitored_resources section.

2771

"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]

2772

# be defined in the Service.logs section. If the log name is

2773

# not a domain scoped name, it will be automatically prefixed with

2774

# 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.

2780

# There can be multiple consumer destinations, each one must have a

2781

# different monitored resource type. A log can be used in at most

2782

# one consumer destination.

2783

{ # Configuration of a specific logging destination (the producer project

2784

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2785

"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]

2786

# Service.monitored_resources section.

2787

"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]

2788

# be defined in the Service.logs section. If the log name is

2789

# not a domain scoped name, it will be automatically prefixed with

2790

# 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,

2797

# e.g. `calendar.googleapis.com`.

2798

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2799

#

2800

# Example:

2801

# <pre><code>documentation:

2802

# summary: >

2803

# The Google Calendar API gives access

2804

# to most calendar features.

2805

# pages:

2806

# - name: Overview

2807

# content: (== include google/foo/overview.md ==)

2808

# - name: Tutorial

2809

# content: (== include google/foo/tutorial.md ==)

2810

# subpages;

2811

# - name: Java

2812

# content: (== include google/foo/tutorial_java.md ==)

2813

# rules:

2814

# - selector: google.calendar.Calendar.Get

2815

# description: >

2816

# ...

2817

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2822

# standard markdown features, definition lists, tables and fenced

2823

# code blocks are supported. Section headers can be provided and are

2824

# interpreted relative to the section nesting of the context where

2825

# a documentation fragment is embedded.

2826

#

2827

# Documentation from the IDL is merged with documentation defined

2828

# via the config at normalization time, where documentation provided

2829

# by config rules overrides IDL provided.

2830

#

2831

# A number of constructs specific to the API platform are supported

2832

# in documentation text.

2833

#

2834

# In order to reference a proto element, the following

2835

# notation can be used:

2836

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2837

# To override the display text used for the link, this can be used:

2838

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2839

# Text can be excluded from doc using the following notation:

2840

# <pre><code>(-- internal comment --)</code></pre>

2841

# Comments can be made conditional using a visibility label. The below

2842

# text will be only rendered if the `BETA` label is available:

2843

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2844

# A few directives are available in documentation. Note that

2845

# directives must appear on a single line to be properly

2846

# identified. The `include` directive includes a markdown file from

2847

# an external source:

2848

# <pre><code>(== include path/to/file ==)</code></pre>

2849

# The `resource_for` directive marks a message to be the resource of

2850

# a collection in REST view. If it is not specified, tools attempt

2851

# to infer the resource from the operations in a collection:

2852

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2853

# The directive `suppress_warning` does not directly affect documentation

2854

# and is documented together with service config validation.

2855

"rules": [ # A list of documentation rules that apply to individual API elements.

2856

#

2857

# **NOTE:** All service configuration rules follow "last one wins" order.

2858

{ # A documentation rule provides information about individual API elements.

2859

"description": "A String", # Description of the selected API(s).

2860

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2861

# element is marked as `deprecated`.

2862

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2863

# qualified name of the element which may end in "*", indicating a wildcard.

2864

# Wildcards are only allowed at the end and for a whole component of the

2865

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2866

# specify a default for all applicable elements, the whole pattern "*"

2867

# is used.

2868

},

2869

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2870

"documentationRootUrl": "A String", # The URL to the root of documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2871

"summary": "A String", # A short summary of what the service does. Can only be provided by

2872

# plain text.

2873

"pages": [ # The top level pages for the documentation set.

2874

{ # Represents a documentation page. A page can contain subpages to represent

2875

# nested documentation set structure.

2876

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2877

# to include content from a Markdown file.

2878

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2879

# honored in the generated docset.

2880

# Object with schema name: Page

2881

],

2882

"name": "A String", # The name of the page. It will be used as an identity of the page to

2883

# generate URI of the page, text of the link to this page in navigation,

2884

# etc. The full page name (start from the root page name to this page

2885

# concatenated with `.`) can be used as reference to the page in your

2886

# documentation. For example:

2887

# <pre><code>pages:

2888

# - name: Tutorial

2889

# content: (== include tutorial.md ==)

2890

# subpages:

2891

# - name: Java

2892

# content: (== include tutorial_java.md ==)

2893

# </code></pre>

2894

# You can reference `Java` page using Markdown reference link syntax:

2895

# `Java`.

2896

},

2897

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2898

"overview": "A String", # Declares a single overview page. For example:

2899

# <pre><code>documentation:

2900

# summary: ...

2901

# overview: (== include overview.md ==)

2902

# </code></pre>

2903

# This is a shortcut for the following declaration (using pages style):

2904

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2909

# </code></pre>

2910

# Note: you cannot specify both `overview` field and `pages` field.

2911

},

2912

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

2913

"sourceFiles": [ # All files used during config generation.

2914

{

2915

"a_key": "", # Properties of the object. Contains field @type with type URL.

2916

},

2917

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2918

},

2919

"systemTypes": [ # A list of all proto message types included in this API service.

2920

# It serves similar purpose as [google.api.Service.types], except that

2921

# these types are not needed by user-defined APIs. Therefore, they will not

2922

# show up in the generated discovery doc. This field should only be used

2923

# to define system APIs in ESF.

2924

{ # A protocol buffer message type.

2925

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2926

"A String",

2927

],

2928

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2929

"fields": [ # The list of fields.

2930

{ # A single field of a message type.

2931

"kind": "A String", # The field type.

2932

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2933

# types. The first type has index 1; zero means the type is not in the list.

2934

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2935

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2936

"name": "A String", # The field name.

2937

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2938

"jsonName": "A String", # The field JSON name.

2939

"number": 42, # The field number.

2940

"cardinality": "A String", # The field cardinality.

2941

"options": [ # The protocol buffer options.

2942

{ # A protocol buffer option, which can be attached to a message, field,

2943

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2944

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2945

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2946

# For custom options, it should be the fully-qualified name. For example,

2947

# `"google.api.http"`.

2948

"value": { # The option's value packed in an Any message. If the value is a primitive,

2949

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2950

# should be used. If the value is an enum, it should be stored as an int32

2951

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2952

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2957

},

2958

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

2959

"syntax": "A String", # The source syntax.

2960

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2961

# protobuf element, like the file in which it is defined.

2962

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2963

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2964

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2965

"options": [ # The protocol buffer options.

2966

{ # A protocol buffer option, which can be attached to a message, field,

2967

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

2968

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2969

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2970

# For custom options, it should be the fully-qualified name. For example,

2971

# `"google.api.http"`.

2972

"value": { # The option's value packed in an Any message. If the value is a primitive,

2973

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2974

# should be used. If the value is an enum, it should be stored as an int32

2975

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2976

"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

2991

# - google.rpc.context.OriginContext

2992

#

2993

# The above specifies that all methods in the API request

2994

# `google.rpc.context.ProjectContext` and

2995

# `google.rpc.context.OriginContext`.

2996

#

2997

# Available context types are defined in package

2998

# `google.rpc.context`.

2999

"rules": [ # A list of RPC context rules that apply to individual API methods.

3000

#

3001

# **NOTE:** All service configuration rules follow "last one wins" order.

3002

{ # A context rule provides information about the context for an individual API

3003

# element.

3004

"provided": [ # A list of full type names of provided contexts.

3005

"A String",

3006

],

3007

"requested": [ # A list of full type names of requested contexts.

3008

"A String",

3009

],

3010

"selector": "A String", # Selects the methods to which this rule applies.

3011

#

3012

# Refer to selector for syntax details.

3013

},

3014

],

3015

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3016

"title": "A String", # The product title associated with this service.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3017

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

3018

# with the same name as the service is automatically generated to service all

3019

# defined APIs.

3020

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

3021

# A service may expose any number of endpoints, and all endpoints share the

3022

# same service configuration, such as quota configuration and monitoring

3023

# configuration.

3024

#

3025

# Example service configuration:

3026

#

3027

# name: library-example.googleapis.com

3028

# endpoints:

3029

# # Below entry makes 'google.example.library.v1.Library'

3030

# # API be served from endpoint address library-example.googleapis.com.

3031

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

3032

# # it to decide whether the subsequent cross-origin request is

3033

# # allowed to proceed.

3034

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3035

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3036

"allowCors": True or False, # Allowing

3037

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

3038

# cross-domain traffic, would allow the backends served from this endpoint to

3039

# receive and respond to HTTP OPTIONS requests. The response will be used by

3040

# the browser to determine whether the subsequent cross-origin request is

3041

# allowed to proceed.

3042

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

3043

# please specify multiple google.api.Endpoint for each of the intented

3044

# alias.

3045

#

3046

# Additional names that this endpoint will be hosted on.

3047

"A String",

3048

],

3049

"features": [ # The list of features enabled on this endpoint.

3050

"A String",

3051

],

3052

"name": "A String", # The canonical name of this endpoint.

3053

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3058

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

3059

# only be used by whitelisted users.

3060

"authorization": { # Configuration of authorization. # Authorization configuration.

3061

#

3062

# This section determines the authorization provider, if unspecified, then no

3063

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

3070

"provider": "A String", # The name of the authorization provider, such as

3071

# firebaserules.googleapis.com.

3072

},

3073

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3078

<code class="details" id="get">get(serviceName=None, configId, x__xgafv=None, view=None)</code>

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3079

<pre>Gets a service configuration (version) for a managed service.

3080

3081

Args:

3082

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3083

for naming requirements. For example: `example.googleapis.com`. (required)

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3084

configId: string, The id of the service configuration resource. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3085

x__xgafv: string, V1 error format.

3086

Allowed values

3087

1 - v1 error format

3088

2 - v2 error format

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3089

view: string, Specifies which parts of the Service Config should be returned in the

3090

response.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3091

3092

Returns:

3093

An object of the form:

3094

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3095

{ # `Service` is the root object of Google service configuration schema. It

3096

# describes basic information about a service, such as the name and the

3097

# title, and delegates other aspects to sub-sections. Each sub-section is

3098

# either a proto message or a repeated proto message that configures a

3099

# 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]

3104

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3105

# name: calendar.googleapis.com

3106

# title: Google Calendar API

3107

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3108

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3109

# authentication:

3110

# providers:

3111

# - id: google_calendar_auth

3112

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3113

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3114

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3115

# - selector: "*"

3116

# requirements:

3117

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3118

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3119

# service controller handles features like abuse, quota, billing, logging,

3120

# monitoring, etc.

3121

"environment": "A String", # The service control environment to use. If empty, no control plane

3122

# feature (like quota and billing) will be enabled.

3123

},

3124

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3125

# by the Service.monitoring and Service.logging configurations.

3126

{ # An object that describes the schema of a MonitoredResource object using a

3127

# type name and a set of labels. For example, the monitored resource

3128

# descriptor for Google Compute Engine VM instances has a type of

3129

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3130

# `"zone"` to identify particular VM instances.

3131

#

3132

# Different APIs can support different monitored resource types. APIs generally

3133

# provide a `list` method that returns the monitored resource descriptors used

3134

# by the API.

3135

"type": "A String", # Required. The monitored resource type. For example, the type

3136

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3137

# The maximum length of this value is 256 characters.

3138

"labels": [ # Required. A set of labels used to describe instances of this monitored

3139

# resource type. For example, an individual Google Cloud SQL database is

3140

# identified by values for the labels `"database_id"` and `"zone"`.

3141

{ # A description of a label.

3142

"valueType": "A String", # The type of data that can be assigned to the label.

3143

"description": "A String", # A human-readable description for the label.

3144

"key": "A String", # The label key.

3145

},

3146

],

3147

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

3148

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3149

# without any article or other determiners. For example,

3150

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3151

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3152

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3153

# {type} is the value of the `type` field in this object and

3154

# {project_id} is a project ID that provides API-specific context for

3155

# accessing the type. APIs that do not use project information can use the

3156

# resource name format `"monitoredResourceDescriptors/{type}"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3157

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3158

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3159

},

3160

],

3161

"logs": [ # Defines the logs used by this service.

3162

{ # A description of a log type. Example in YAML format:

3163

#

3164

# - name: library.googleapis.com/activity_history

3165

# description: The history of borrowing and returning library items.

3166

# display_name: Activity

3167

# labels:

3168

# - key: /customer_id

3169

# description: Identifier of a library customer

3170

"labels": [ # The set of labels that are available to describe a specific log entry.

3171

# Runtime requests that contain labels not specified here are

3172

# considered invalid.

3173

{ # A description of a label.

3174

"valueType": "A String", # The type of data that can be assigned to the label.

3175

"description": "A String", # A human-readable description for the label.

3176

"key": "A String", # The label key.

3177

},

3178

],

3179

"displayName": "A String", # The human-readable name for this log. This information appears on

3180

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3181

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3182

# include the following characters: upper- and lower-case alphanumeric

3183

# characters [A-Za-z0-9], and punctuation characters including

3184

# slash, underscore, hyphen, period [/_-.].

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3185

"description": "A String", # A human-readable description of this log. This information appears in

3186

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3187

},

3188

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3189

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3190

# by the client for tracking purpose. If empty, the server may choose to

3191

# generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3192

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3193

"rules": [ # A list of API backend rules that apply to individual API methods.

3194

#

3195

# **NOTE:** All service configuration rules follow "last one wins" order.

3196

{ # A backend rule provides configuration for an individual API element.

3197

"selector": "A String", # Selects the methods to which this rule applies.

3198

#

3199

# Refer to selector for syntax details.

3200

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

3201

# default depends on the deployment context.

3202

"address": "A String", # The address of the API backend.

3203

},

3204

],

3205

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3206

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3207

#

3208

# The example below shows how to configure monitored resources and metrics

3209

# for monitoring. In the example, a monitored resource and two metrics are

3210

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3211

# to both producer and consumer projects, whereas the

3212

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3213

# consumer project.

3214

#

3215

# monitored_resources:

3216

# - type: library.googleapis.com/branch

3217

# labels:

3218

# - key: /city

3219

# description: The city where the library branch is located in.

3220

# - key: /name

3221

# description: The name of the branch.

3222

# metrics:

3223

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3228

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3233

# monitoring:

3234

# producer_destinations:

3235

# - monitored_resource: library.googleapis.com/branch

3236

# metrics:

3237

# - library.googleapis.com/book/returned_count

3238

# consumer_destinations:

3239

# - monitored_resource: library.googleapis.com/branch

3240

# metrics:

3241

# - library.googleapis.com/book/returned_count

3242

# - library.googleapis.com/book/overdue_count

3243

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3244

# There can be multiple producer destinations, each one must have a

3245

# different monitored resource type. A metric can be used in at most

3246

# one producer destination.

3247

{ # Configuration of a specific monitoring destination (the producer project

3248

# or the consumer project).

3249

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3250

# Service.monitored_resources section.

3251

"metrics": [ # Names of the metrics to report to this monitoring destination.

3252

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3258

# There can be multiple consumer destinations, each one must have a

3259

# different monitored resource type. A metric can be used in at most

3260

# one consumer destination.

3261

{ # Configuration of a specific monitoring destination (the producer project

3262

# or the consumer project).

3263

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3264

# Service.monitored_resources section.

3265

"metrics": [ # Names of the metrics to report to this monitoring destination.

3266

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3272

"systemParameters": { # ### System parameter configuration # System parameter configuration.

3273

#

3274

# A system parameter is a special kind of parameter defined by the API

3275

# system, not by an individual API. It is typically mapped to an HTTP header

3276

# and/or a URL query parameter. This configuration specifies which methods

3277

# change the names of the system parameters.

3278

"rules": [ # Define system parameters.

3279

#

3280

# The parameters defined here will override the default parameters

3281

# implemented by the system. If this field is missing from the service

3282

# config, default system parameters will be used. Default system parameters

3283

# and names is implementation-dependent.

3284

#

3285

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3293

#

3294

#

3295

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3300

# parameters:

3301

# - name: api_key

3302

# http_header: Api-Key1

3303

# - name: api_key

3304

# http_header: Api-Key2

3305

#

3306

# **NOTE:** All service configuration rules follow "last one wins" order.

3307

{ # Define a system parameter rule mapping system parameter definitions to

3308

# methods.

3309

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3310

# For a given method call, only one of them should be used. If multiple

3311

# names are used the behavior is implementation-dependent.

3312

# If none of the specified names are present the behavior is

3313

# parameter-dependent.

3314

{ # Define a parameter's name and location. The parameter may be passed as either

3315

# an HTTP header or a URL query parameter, and if both are passed the behavior

3316

# is implementation-dependent.

3317

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3318

# sensitive.

3319

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

3320

# insensitive.

3321

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

3322

},

3323

],

3324

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3325

# methods in all APIs.

3326

#

3327

# Refer to selector for syntax details.

3328

},

3329

],

3330

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3331

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3332

#

3333

# Example for an API targeted for external use:

3334

#

3335

# name: calendar.googleapis.com

3336

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3337

# providers:

3338

# - id: google_calendar_auth

3339

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3340

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3341

# rules:

3342

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3343

# requirements:

3344

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3345

"rules": [ # A list of authentication rules that apply to individual API methods.

3346

#

3347

# **NOTE:** All service configuration rules follow "last one wins" order.

3348

{ # Authentication rules for the service.

3349

#

3350

# By default, if a method has any authentication requirements, every request

3351

# must include a valid credential matching one of the requirements.

3352

# It's an error to include more than one kind of credential in a single

3353

# request.

3354

#

3355

# If a method doesn't have any auth requirements, request credentials will be

3356

# ignored.

3357

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3358

# there are scopes defined for "Read-only access to Google Calendar" and

3359

# "Access to Cloud Platform". Users can consent to a scope for an application,

3360

# giving it permission to access that data on their behalf.

3361

#

3362

# OAuth scope specifications should be fairly coarse grained; a user will need

3363

# to see and understand the text description of what your scope means.

3364

#

3365

# In most cases: use one or at most two OAuth scopes for an entire family of

3366

# products. If your product has multiple APIs, you should probably be sharing

3367

# the OAuth scope across all of those APIs.

3368

#

3369

# When you need finer grained OAuth consent screens: talk with your product

3370

# management about how developers will use them in practice.

3371

#

3372

# Please note that even though each of the canonical scopes is enough for a

3373

# request to be accepted and passed to the backend, a request can still fail

3374

# due to the backend requiring additional scopes or permissions.

3375

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3376

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3381

# https://www.googleapis.com/auth/calendar.read

3382

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3383

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3384

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3385

#

3386

# For requests without credentials, if the service control environment is

3387

# specified, each incoming request **must** be associated with a service

3388

# consumer. This can be done by passing an API key that belongs to a consumer

3389

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3390

"requirements": [ # Requirements for additional authentication providers.

3391

{ # User-defined authentication requirements, including support for

3392

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3393

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3398

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3399

# implemented and accepted in all the runtime components.

3400

#

3401

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3402

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3403

# that are allowed to access. A JWT containing any of these audiences will

3404

# be accepted. When this setting is absent, only JWTs with audience

3405

# "https://Service_name/API_name"

3406

# will be accepted. For example, if no audiences are in the setting,

3407

# LibraryService API will only accept JWTs with the following audience

3408

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3413

# bookstore_web.apps.googleusercontent.com

3414

},

3415

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3416

"selector": "A String", # Selects the methods to which this rule applies.

3417

#

3418

# Refer to selector for syntax details.

3419

},

3420

],

3421

"providers": [ # Defines a set of authentication providers that a service supports.

3422

{ # Configuration for an anthentication provider, including support for

3423

# [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]

3424

"audiences": "A String", # The list of JWT

3425

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3426

# that are allowed to access. A JWT containing any of these audiences will

3427

# be accepted. When this setting is absent, only JWTs with audience

3428

# "https://Service_name/API_name"

3429

# will be accepted. For example, if no audiences are in the setting,

3430

# LibraryService API will only accept JWTs with the following audience

3431

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3436

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3437

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3438

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3439

# Optional if the key set document:

3440

# - can be retrieved from

3441

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3442

# of the issuer.

3443

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3444

#

3445

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3446

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3447

# `AuthRequirement.provider_id`.

3448

#

3449

# Example: "bookstore_auth".

3450

"issuer": "A String", # Identifies the principal that issued the JWT. See

3451

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3452

# Usually a URL or an email address.

3453

#

3454

# Example: https://securetoken.google.com

3455

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3460

"rules": [ # A list of usage rules that apply to individual API methods.

3461

#

3462

# **NOTE:** All service configuration rules follow "last one wins" order.

3463

{ # Usage configuration rules for the service.

3464

#

3465

# NOTE: Under development.

3466

#

3467

#

3468

# Use this rule to configure unregistered calls for the service. Unregistered

3469

# calls are calls that do not contain consumer project identity.

3470

# (Example: calls that do not contain an API key).

3471

# By default, API methods do not allow unregistered calls, and each method call

3472

# must be identified by a consumer project identity. Use this rule to

3473

# allow/disallow unregistered calls.

3474

#

3475

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3481

#

3482

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3487

# allow_unregistered_calls: true

3488

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3489

# methods in all APIs.

3490

#

3491

# Refer to selector for syntax details.

3492

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3493

},

3494

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3495

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

3496

# service producer.

3497

#

3498

# Google Service Management currently only supports

3499

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

3500

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

3501

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

3502

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3503

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3504

# service. Each requirement is of the form <service.name>/<requirement-id>;

3505

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3510

# influence interpretation of the configuration, for example, to

3511

# determine defaults. This is documented together with applicable

3512

# options. The current default for the config version itself is `3`.

3513

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3514

# Members of this project can manage the service configuration,

3515

# manage consumption of the service, etc.

3516

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3517

# HttpRule, each specifying the mapping of an RPC method

3518

# to one or more HTTP REST API methods.

3519

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3520

#

3521

# **NOTE:** All service configuration rules follow "last one wins" order.

3522

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3523

# REST APIs. The mapping determines what portions of the request

3524

# message are populated from the path, query parameters, or body of

3525

# the HTTP request. The mapping is typically specified as an

3526

# `google.api.http` annotation, see "google/api/annotations.proto"

3527

# for details.

3528

#

3529

# The mapping consists of a field specifying the path template and

3530

# method kind. The path template can refer to fields in the request

3531

# message, as in the example below which describes a REST GET

3532

# operation on a resource collection of messages:

3533

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3534

#

3535

# service Messaging {

3536

# rpc GetMessage(GetMessageRequest) returns (Message) {

3537

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3538

# }

3539

# }

3540

# message GetMessageRequest {

3541

# message SubMessage {

3542

# string subfield = 1;

3543

# }

3544

# string message_id = 1; // mapped to the URL

3545

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3546

# }

3547

# message Message {

3548

# string text = 1; // content of the resource

3549

# }

3550

#

3551

# The same http annotation can alternatively be expressed inside the

3552

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

3557

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3558

#

3559

# This definition enables an automatic, bidrectional mapping of HTTP

3560

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3565

#

3566

# In general, not only fields but also field paths can be referenced

3567

# from a path pattern. Fields mapped to the path pattern cannot be

3568

# repeated and must have a primitive (non-message) type.

3569

#

3570

# Any fields in the request message which are not bound by the path

3571

# pattern automatically become (optional) HTTP query

3572

# parameters. Assume the following definition of the request message:

3573

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3574

#

3575

# message GetMessageRequest {

3576

# message SubMessage {

3577

# string subfield = 1;

3578

# }

3579

# string message_id = 1; // mapped to the URL

3580

# int64 revision = 2; // becomes a parameter

3581

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

3582

# }

3583

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3584

#

3585

# 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"))`

3590

#

3591

# Note that fields which are mapped to HTTP parameters must have a

3592

# primitive type or a repeated primitive type. Message types are not

3593

# allowed. In the case of a repeated type, the parameter can be

3594

# repeated in the URL, as in `...?param=A&param=B`.

3595

#

3596

# For HTTP method kinds which allow a request body, the `body` field

3597

# specifies the mapping. Consider a REST update method on the

3598

# message resource collection:

3599

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3600

#

3601

# service Messaging {

3602

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3603

# option (google.api.http) = {

3604

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3610

# string message_id = 1; // mapped to the URL

3611

# Message message = 2; // mapped to the body

3612

# }

3613

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3614

#

3615

# The following HTTP JSON to RPC mapping is enabled, where the

3616

# representation of the JSON in the request body is determined by

3617

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3622

#

3623

# The special name `*` can be used in the body mapping to define that

3624

# every field not bound by the path template should be mapped to the

3625

# request body. This enables the following alternative definition of

3626

# the update method:

3627

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3628

# service Messaging {

3629

# rpc UpdateMessage(Message) returns (Message) {

3630

# option (google.api.http) = {

3631

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

3638

# string text = 2;

3639

# }

3640

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3641

#

3642

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

3647

#

3648

# Note that when using `*` in the body mapping, it is not possible to

3649

# have HTTP parameters, as all fields not bound by the path end in

3650

# the body. This makes this option more rarely used in practice of

3651

# defining REST APIs. The common usage of `*` is in custom methods

3652

# which don't use the URL at all for transferring data.

3653

#

3654

# It is possible to define multiple HTTP methods for one RPC by using

3655

# the `additional_bindings` option. Example:

3656

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3657

# service Messaging {

3658

# rpc GetMessage(GetMessageRequest) returns (Message) {

3659

# option (google.api.http) = {

3660

# get: "/v1/messages/{message_id}"

3661

# additional_bindings {

3662

# get: "/v1/users/{user_id}/messages/{message_id}"

3663

# }

3664

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3665

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3666

# }

3667

# message GetMessageRequest {

3668

# string message_id = 1;

3669

# string user_id = 2;

3670

# }

3671

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3672

#

3673

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

3679

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

3680

#

3681

# # Rules for HTTP mapping

3682

#

3683

# The rules for mapping HTTP path, query parameters, and body fields

3684

# to the request message are as follows:

3685

#

3686

# 1. The `body` field specifies either `*` or a field path, or is

3687

# omitted. If omitted, it assumes there is no HTTP body.

3688

# 2. Leaf fields (recursive expansion of nested messages in the

3689

# request) can be classified into three types:

3690

# (a) Matched in the URL template.

3691

# (b) Covered by body (if body is `*`, everything except (a) fields;

3692

# else everything under the body field)

3693

# (c) All other fields.

3694

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

3695

# 4. Any body sent with an HTTP request can contain only (b) fields.

3696

#

3697

# The syntax of the path template is as follows:

3698

#

3699

# Template = "/" Segments [ Verb ] ;

3700

# Segments = Segment { "/" Segment } ;

3701

# Segment = "*" | "**" | LITERAL | Variable ;

3702

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3703

# FieldPath = IDENT { "." IDENT } ;

3704

# Verb = ":" LITERAL ;

3705

#

3706

# The syntax `*` matches a single path segment. It follows the semantics of

3707

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3708

# Expansion.

3709

#

3710

# The syntax `**` matches zero or more path segments. It follows the semantics

3711

# 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]

3712

# 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]

3713

#

3714

# The syntax `LITERAL` matches literal text in the URL path.

3715

#

3716

# The syntax `Variable` matches the entire path as specified by its template;

3717

# this nested template must not contain further variables. If a variable

3718

# matches a single path segment, its template may be omitted, e.g. `{var}`

3719

# is equivalent to `{var=*}`.

3720

#

3721

# NOTE: the field paths in variables and in the `body` must not refer to

3722

# repeated fields or map fields.

3723

#

3724

# Use CustomHttpPattern to specify any HTTP method that is not included in the

3725

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

3726

# a given URL path rule. The wild-card rule is useful for services that provide

3727

# content to Web (HTML) clients.

3728

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

3729

# `*` for mapping all fields not captured by the path pattern to the HTTP

3730

# 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]

3731

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3732

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3733

"mediaDownload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for bytestream methods.

3734

# For media support, add instead [][google.bytestream.RestByteStream] as an

3735

# API to your configuration.

3736

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

3737

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3738

"enabled": True or False, # Whether download is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3739

"downloadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

3740

#

3741

# Specify name of the download service if one is used for download.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3742

},

3743

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3744

# not contain an `additional_bindings` field themselves (that is,

3745

# the nesting may only be one level deep).

3746

# Object with schema name: HttpRule

3747

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3748

"mediaUpload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for media support using

3749

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3750

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3751

# configuration for Bytestream methods.

3752

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

3753

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3754

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3755

"uploadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

3756

#

3757

# Specify name of the upload service if one is used for upload.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3758

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3759

"selector": "A String", # Selects methods to which this rule applies.

3760

#

3761

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3762

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

3763

# response. Other response fields are ignored. This field is optional. When

3764

# not set, the response message will be used as HTTP body of response.

3765

# NOTE: the referred field must be not a repeated field and must be present

3766

# at the top-level of response message type.

3767

"put": "A String", # Used for updating a resource.

3768

"patch": "A String", # Used for updating a resource.

3769

"post": "A String", # Used for creating a resource.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

3770

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

3771

"path": "A String", # The path matched by this custom verb.

3772

"kind": "A String", # The name of this custom HTTP verb.

3773

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3774

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3779

# of the google.protobuf.Api needs to be provided by the configuration

3780

# author, as the remaining fields will be derived from the IDL during the

3781

# normalization process. It is an error to specify an API interface here

3782

# which cannot be resolved against the associated IDL files.

3783

{ # Api is a light-weight descriptor for a protocol buffer service.

3784

"methods": [ # The methods of this api, in unspecified order.

3785

{ # Method represents a method of an api.

3786

"name": "A String", # The simple name of this method.

3787

"requestStreaming": True or False, # If true, the request is streamed.

3788

"responseTypeUrl": "A String", # The URL of the output message type.

3789

"requestTypeUrl": "A String", # A URL of the input message type.

3790

"responseStreaming": True or False, # If true, the response is streamed.

3791

"syntax": "A String", # The source syntax of this method.

3792

"options": [ # Any metadata attached to the method.

3793

{ # A protocol buffer option, which can be attached to a message, field,

3794

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3795

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3796

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3797

# For custom options, it should be the fully-qualified name. For example,

3798

# `"google.api.http"`.

3799

"value": { # The option's value packed in an Any message. If the value is a primitive,

3800

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3801

# should be used. If the value is an enum, it should be stored as an int32

3802

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3803

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

3810

# message.

3811

# protobuf element, like the file in which it is defined.

3812

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3813

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3814

},

3815

"mixins": [ # Included APIs. See Mixin.

3816

{ # Declares an API to be included in this API. The including API must

3817

# redeclare all the methods from the included API, but documentation

3818

# and options are inherited as follows:

3819

#

3820

# - If after comment and whitespace stripping, the documentation

3821

# string of the redeclared method is empty, it will be inherited

3822

# from the original method.

3823

#

3824

# - Each annotation belonging to the service config (http,

3825

# visibility) which is not set in the redeclared method will be

3826

# inherited.

3827

#

3828

# - If an http annotation is inherited, the path pattern will be

3829

# modified as follows. Any version prefix will be replaced by the

3830

# version of the including API plus the root path if specified.

3831

#

3832

# Example of a simple mixin:

3833

#

3834

# package google.acl.v1;

3835

# service AccessControl {

3836

# // Get the underlying ACL object.

3837

# rpc GetAcl(GetAclRequest) returns (Acl) {

3838

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3843

# service Storage {

3844

# // rpc GetAcl(GetAclRequest) returns (Acl);

3845

#

3846

# // Get a data record.

3847

# rpc GetData(GetDataRequest) returns (Data) {

3848

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3853

#

3854

# apis:

3855

# - name: google.storage.v2.Storage

3856

# mixins:

3857

# - name: google.acl.v1.AccessControl

3858

#

3859

# The mixin construct implies that all methods in `AccessControl` are

3860

# also declared with same name and request/response types in

3861

# `Storage`. A documentation generator or annotation processor will

3862

# see the effective `Storage.GetAcl` method after inherting

3863

# documentation and annotations as follows:

3864

#

3865

# service Storage {

3866

# // Get the underlying ACL object.

3867

# rpc GetAcl(GetAclRequest) returns (Acl) {

3868

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3874

#

3875

# If the `root` field in the mixin is specified, it should be a

3876

# relative path under which inherited HTTP paths are placed. Example:

3877

#

3878

# apis:

3879

# - name: google.storage.v2.Storage

3880

# mixins:

3881

# - name: google.acl.v1.AccessControl

3882

# root: acls

3883

#

3884

# This implies the following inherited HTTP annotation:

3885

#

3886

# service Storage {

3887

# // Get the underlying ACL object.

3888

# rpc GetAcl(GetAclRequest) returns (Acl) {

3889

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3894

# are rooted.

3895

"name": "A String", # The fully qualified name of the API which is included.

3896

},

3897

],

3898

"syntax": "A String", # The source syntax of the service.

3899

"version": "A String", # A version string for this api. If specified, must have the form

3900

# `major-version.minor-version`, as in `1.10`. If the minor version

3901

# is omitted, it defaults to zero. If the entire version field is

3902

# empty, the major version is derived from the package name, as

3903

# outlined below. If the field is not empty, the version in the

3904

# package name will be verified to be consistent with what is

3905

# provided here.

3906

#

3907

# The versioning schema uses [semantic

3908

# versioning](http://semver.org) where the major version number

3909

# indicates a breaking change and the minor version an additive,

3910

# non-breaking change. Both version numbers are signals to users

3911

# what to expect from different versions, and should be carefully

3912

# chosen based on the product plan.

3913

#

3914

# The major version is also reflected in the package name of the

3915

# API, which must end in `v<major-version>`, as in

3916

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3917

# be omitted. Zero major versions must only be used for

3918

# experimental, none-GA apis.

3919

"options": [ # Any metadata attached to the API.

3920

{ # A protocol buffer option, which can be attached to a message, field,

3921

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

3922

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3923

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3924

# For custom options, it should be the fully-qualified name. For example,

3925

# `"google.api.http"`.

3926

"value": { # The option's value packed in an Any message. If the value is a primitive,

3927

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3928

# should be used. If the value is an enum, it should be stored as an int32

3929

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3930

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

3935

# followed by the api's simple name.

3936

},

3937

],

3938

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3939

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3947

# - google.foo.v1.AnotherError

3948

"rules": [ # The list of custom error rules that apply to individual API messages.

3949

#

3950

# **NOTE:** All service configuration rules follow "last one wins" order.

3951

{ # A custom error rule.

3952

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3953

# objects of this type will be filtered when they appear in error payload.

3954

"selector": "A String", # Selects messages to which this rule applies.

3955

#

3956

# Refer to selector for syntax details.

3957

},

3958

],

3959

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

3964

# elements. Restrictions are specified using visibility labels

3965

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3966

#

3967

# Users and projects can have access to more than one visibility label. The

3968

# effective visibility for multiple labels is the union of each label's

3969

# elements, plus any unrestricted elements.

3970

#

3971

# If an element and its parents have no restrictions, visibility is

3972

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3979

# restriction: TRUSTED_TESTER

3980

# - selector: google.calendar.Calendar.Delegate

3981

# restriction: GOOGLE_INTERNAL

3982

#

3983

# Here, all methods are publicly visible except for the restricted methods

3984

# EnhancedSearch and Delegate.

3985

"rules": [ # A list of visibility rules that apply to individual API elements.

3986

#

3987

# **NOTE:** All service configuration rules follow "last one wins" order.

3988

{ # A visibility rule provides visibility configuration for an individual API

3989

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3990

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

3991

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3992

#

3993

# If a rule has multiple labels, removing one of the labels but not all of

3994

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

4001

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

4002

#

4003

# Removing GOOGLE_INTERNAL from this restriction will break clients that

4004

# rely on this method and only had access to it through GOOGLE_INTERNAL.

4005

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

4006

#

4007

# 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]

4012

{ # Defines a metric type and its schema. Once a metric descriptor is created,

4013

# deleting or altering it stops data collection and makes the metric type's

4014

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4015

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

4016

# Use sentence case without an ending period, for example "Request count".

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4017

"name": "A String", # The resource name of the metric descriptor. Depending on the

4018

# implementation, the name typically includes: (1) the parent resource name

4019

# that defines the scope of the metric type or of its data; and (2) the

4020

# metric's URL-encoded type, which also appears in the `type` field of this

4021

# descriptor. For example, following is the resource name of a custom

4022

# metric within the GCP project `my-project-id`:

4023

#

4024

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4025

"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]

4026

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4027

"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]

4028

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4029

"labels": [ # The set of labels that can be used to describe a specific

4030

# instance of this metric type. For example, the

4031

# `appengine.googleapis.com/http/server/response_latencies` metric

4032

# type has a label for the HTTP response code, `response_code`, so

4033

# you can look at latencies for successful responses or just

4034

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4035

{ # A description of a label.

4036

"valueType": "A String", # The type of data that can be assigned to the label.

4037

"description": "A String", # A human-readable description for the label.

4038

"key": "A String", # The label key.

4039

},

4040

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4041

"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^]

4042

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4043

# `custom.googleapis.com`. Metric types should use a natural hierarchical

4044

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4045

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4046

# "custom.googleapis.com/invoice/paid/amount"

4047

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4048

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

4049

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

4050

# supported units are a subset of [The Unified Code for Units of

4051

# Measure](http://unitsofmeasure.org/ucum.html) standard:

4052

#

4053

# **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)

4068

# * `P` peta (10**15)

4069

# * `E` exa (10**18)

4070

# * `Z` zetta (10**21)

4071

# * `Y` yotta (10**24)

4072

# * `m` milli (10**-3)

4073

# * `u` micro (10**-6)

4074

# * `n` nano (10**-9)

4075

# * `p` pico (10**-12)

4076

# * `f` femto (10**-15)

4077

# * `a` atto (10**-18)

4078

# * `z` zepto (10**-21)

4079

# * `y` yocto (10**-24)

4080

# * `Ki` kibi (2**10)

4081

# * `Mi` mebi (2**20)

4082

# * `Gi` gibi (2**30)

4083

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

4088

#

4089

# The grammar also includes these connectors:

4090

#

4091

# * `/` division (as an infix operator, e.g. `1/s`).

4092

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

4093

#

4094

# The grammar for a unit is as follows:

4095

#

4096

# Expression = Component { "." Component } { "/" Component } ;

4097

#

4098

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

4108

# equivalent to `1` if it is used alone. For examples,

4109

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

4110

# * `NAME` is a sequence of non-blank printable ASCII characters not

4111

# containing '{' or '}'.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4112

"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]

4113

},

4114

],

4115

"enums": [ # A list of all enum types included in this API service. Enums

4116

# referenced directly or indirectly by the `apis` are automatically

4117

# included. Enums which are not referenced but shall be included

4118

# should be listed here by name. Example:

4119

#

4120

# enums:

4121

# - name: google.someapi.v1.SomeEnum

4122

{ # Enum type definition.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4123

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4124

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4125

# protobuf element, like the file in which it is defined.

4126

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4127

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4128

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4129

"options": [ # Protocol buffer options.

4130

{ # A protocol buffer option, which can be attached to a message, field,

4131

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4132

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4133

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4134

# For custom options, it should be the fully-qualified name. For example,

4135

# `"google.api.http"`.

4136

"value": { # The option's value packed in an Any message. If the value is a primitive,

4137

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4138

# should be used. If the value is an enum, it should be stored as an int32

4139

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4140

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4145

"enumvalue": [ # Enum value definitions.

4146

{ # Enum value definition.

4147

"options": [ # Protocol buffer options.

4148

{ # A protocol buffer option, which can be attached to a message, field,

4149

# enumeration, etc.

4150

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4151

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4152

# For custom options, it should be the fully-qualified name. For example,

4153

# `"google.api.http"`.

4154

"value": { # The option's value packed in an Any message. If the value is a primitive,

4155

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4156

# should be used. If the value is an enum, it should be stored as an int32

4157

# value using the google.protobuf.Int32Value type.

4158

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"number": 42, # Enum value number.

4163

"name": "A String", # Enum value name.

4164

},

4165

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4166

},

4167

],

4168

"types": [ # A list of all proto message types included in this API service.

4169

# Types referenced directly or indirectly by the `apis` are

4170

# automatically included. Messages which are not referenced but

4171

# shall be included, such as types used by the `google.protobuf.Any` type,

4172

# should be listed here by name. Example:

4173

#

4174

# types:

4175

# - name: google.protobuf.Int32

4176

{ # A protocol buffer message type.

4177

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4178

"A String",

4179

],

4180

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4181

"fields": [ # The list of fields.

4182

{ # A single field of a message type.

4183

"kind": "A String", # The field type.

4184

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4185

# types. The first type has index 1; zero means the type is not in the list.

4186

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4187

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4188

"name": "A String", # The field name.

4189

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4190

"jsonName": "A String", # The field JSON name.

4191

"number": 42, # The field number.

4192

"cardinality": "A String", # The field cardinality.

4193

"options": [ # The protocol buffer options.

4194

{ # A protocol buffer option, which can be attached to a message, field,

4195

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4196

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4197

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4198

# For custom options, it should be the fully-qualified name. For example,

4199

# `"google.api.http"`.

4200

"value": { # The option's value packed in an Any message. If the value is a primitive,

4201

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4202

# should be used. If the value is an enum, it should be stored as an int32

4203

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4204

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4209

},

4210

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4211

"syntax": "A String", # The source syntax.

4212

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4213

# protobuf element, like the file in which it is defined.

4214

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4215

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4216

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4217

"options": [ # The protocol buffer options.

4218

{ # A protocol buffer option, which can be attached to a message, field,

4219

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4220

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4221

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4222

# For custom options, it should be the fully-qualified name. For example,

4223

# `"google.api.http"`.

4224

"value": { # The option's value packed in an Any message. If the value is a primitive,

4225

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4226

# should be used. If the value is an enum, it should be stored as an int32

4227

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4228

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4234

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4235

#

4236

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4237

# producer and consumer projects. In the example, the `activity_history`

4238

# log is sent to both the producer and consumer projects, whereas the

4239

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4240

#

4241

# monitored_resources:

4242

# - type: library.googleapis.com/branch

4243

# labels:

4244

# - key: /city

4245

# description: The city where the library branch is located in.

4246

# - key: /name

4247

# description: The name of the branch.

4248

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4249

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4250

# labels:

4251

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4252

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4253

# logging:

4254

# producer_destinations:

4255

# - monitored_resource: library.googleapis.com/branch

4256

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4257

# - activity_history

4258

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4259

# consumer_destinations:

4260

# - monitored_resource: library.googleapis.com/branch

4261

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4262

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4263

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4264

# There can be multiple producer destinations, each one must have a

4265

# different monitored resource type. A log can be used in at most

4266

# one producer destination.

4267

{ # Configuration of a specific logging destination (the producer project

4268

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4269

"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]

4270

# Service.monitored_resources section.

4271

"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]

4272

# be defined in the Service.logs section. If the log name is

4273

# not a domain scoped name, it will be automatically prefixed with

4274

# 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.

4280

# There can be multiple consumer destinations, each one must have a

4281

# different monitored resource type. A log can be used in at most

4282

# one consumer destination.

4283

{ # Configuration of a specific logging destination (the producer project

4284

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4285

"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]

4286

# Service.monitored_resources section.

4287

"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]

4288

# be defined in the Service.logs section. If the log name is

4289

# not a domain scoped name, it will be automatically prefixed with

4290

# 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,

4297

# e.g. `calendar.googleapis.com`.

4298

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4299

#

4300

# Example:

4301

# <pre><code>documentation:

4302

# summary: >

4303

# The Google Calendar API gives access

4304

# to most calendar features.

4305

# pages:

4306

# - name: Overview

4307

# content: (== include google/foo/overview.md ==)

4308

# - name: Tutorial

4309

# content: (== include google/foo/tutorial.md ==)

4310

# subpages;

4311

# - name: Java

4312

# content: (== include google/foo/tutorial_java.md ==)

4313

# rules:

4314

# - selector: google.calendar.Calendar.Get

4315

# description: >

4316

# ...

4317

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

4322

# standard markdown features, definition lists, tables and fenced

4323

# code blocks are supported. Section headers can be provided and are

4324

# interpreted relative to the section nesting of the context where

4325

# a documentation fragment is embedded.

4326

#

4327

# Documentation from the IDL is merged with documentation defined

4328

# via the config at normalization time, where documentation provided

4329

# by config rules overrides IDL provided.

4330

#

4331

# A number of constructs specific to the API platform are supported

4332

# in documentation text.

4333

#

4334

# In order to reference a proto element, the following

4335

# notation can be used:

4336

# <pre><code>[fully.qualified.proto.name][]</code></pre>

4337

# To override the display text used for the link, this can be used:

4338

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

4339

# Text can be excluded from doc using the following notation:

4340

# <pre><code>(-- internal comment --)</code></pre>

4341

# Comments can be made conditional using a visibility label. The below

4342

# text will be only rendered if the `BETA` label is available:

4343

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

4344

# A few directives are available in documentation. Note that

4345

# directives must appear on a single line to be properly

4346

# identified. The `include` directive includes a markdown file from

4347

# an external source:

4348

# <pre><code>(== include path/to/file ==)</code></pre>

4349

# The `resource_for` directive marks a message to be the resource of

4350

# a collection in REST view. If it is not specified, tools attempt

4351

# to infer the resource from the operations in a collection:

4352

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

4353

# The directive `suppress_warning` does not directly affect documentation

4354

# and is documented together with service config validation.

4355

"rules": [ # A list of documentation rules that apply to individual API elements.

4356

#

4357

# **NOTE:** All service configuration rules follow "last one wins" order.

4358

{ # A documentation rule provides information about individual API elements.

4359

"description": "A String", # Description of the selected API(s).

4360

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

4361

# element is marked as `deprecated`.

4362

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

4363

# qualified name of the element which may end in "*", indicating a wildcard.

4364

# Wildcards are only allowed at the end and for a whole component of the

4365

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

4366

# specify a default for all applicable elements, the whole pattern "*"

4367

# is used.

4368

},

4369

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4370

"documentationRootUrl": "A String", # The URL to the root of documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4371

"summary": "A String", # A short summary of what the service does. Can only be provided by

4372

# plain text.

4373

"pages": [ # The top level pages for the documentation set.

4374

{ # Represents a documentation page. A page can contain subpages to represent

4375

# nested documentation set structure.

4376

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

4377

# to include content from a Markdown file.

4378

"subpages": [ # Subpages of this page. The order of subpages specified here will be

4379

# honored in the generated docset.

4380

# Object with schema name: Page

4381

],

4382

"name": "A String", # The name of the page. It will be used as an identity of the page to

4383

# generate URI of the page, text of the link to this page in navigation,

4384

# etc. The full page name (start from the root page name to this page

4385

# concatenated with `.`) can be used as reference to the page in your

4386

# documentation. For example:

4387

# <pre><code>pages:

4388

# - name: Tutorial

4389

# content: (== include tutorial.md ==)

4390

# subpages:

4391

# - name: Java

4392

# content: (== include tutorial_java.md ==)

4393

# </code></pre>

4394

# You can reference `Java` page using Markdown reference link syntax:

4395

# `Java`.

4396

},

4397

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4398

"overview": "A String", # Declares a single overview page. For example:

4399

# <pre><code>documentation:

4400

# summary: ...

4401

# overview: (== include overview.md ==)

4402

# </code></pre>

4403

# This is a shortcut for the following declaration (using pages style):

4404

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

4409

# </code></pre>

4410

# Note: you cannot specify both `overview` field and `pages` field.

4411

},

4412

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

4413

"sourceFiles": [ # All files used during config generation.

4414

{

4415

"a_key": "", # Properties of the object. Contains field @type with type URL.

4416

},

4417

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4418

},

4419

"systemTypes": [ # A list of all proto message types included in this API service.

4420

# It serves similar purpose as [google.api.Service.types], except that

4421

# these types are not needed by user-defined APIs. Therefore, they will not

4422

# show up in the generated discovery doc. This field should only be used

4423

# to define system APIs in ESF.

4424

{ # A protocol buffer message type.

4425

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4426

"A String",

4427

],

4428

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4429

"fields": [ # The list of fields.

4430

{ # A single field of a message type.

4431

"kind": "A String", # The field type.

4432

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4433

# types. The first type has index 1; zero means the type is not in the list.

4434

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4435

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4436

"name": "A String", # The field name.

4437

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4438

"jsonName": "A String", # The field JSON name.

4439

"number": 42, # The field number.

4440

"cardinality": "A String", # The field cardinality.

4441

"options": [ # The protocol buffer options.

4442

{ # A protocol buffer option, which can be attached to a message, field,

4443

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4444

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4445

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4446

# For custom options, it should be the fully-qualified name. For example,

4447

# `"google.api.http"`.

4448

"value": { # The option's value packed in an Any message. If the value is a primitive,

4449

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4450

# should be used. If the value is an enum, it should be stored as an int32

4451

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4452

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4457

},

4458

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4459

"syntax": "A String", # The source syntax.

4460

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4461

# protobuf element, like the file in which it is defined.

4462

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4463

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4464

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4465

"options": [ # The protocol buffer options.

4466

{ # A protocol buffer option, which can be attached to a message, field,

4467

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4468

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4469

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4470

# For custom options, it should be the fully-qualified name. For example,

4471

# `"google.api.http"`.

4472

"value": { # The option's value packed in an Any message. If the value is a primitive,

4473

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4474

# should be used. If the value is an enum, it should be stored as an int32

4475

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4476

"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

4491

# - google.rpc.context.OriginContext

4492

#

4493

# The above specifies that all methods in the API request

4494

# `google.rpc.context.ProjectContext` and

4495

# `google.rpc.context.OriginContext`.

4496

#

4497

# Available context types are defined in package

4498

# `google.rpc.context`.

4499

"rules": [ # A list of RPC context rules that apply to individual API methods.

4500

#

4501

# **NOTE:** All service configuration rules follow "last one wins" order.

4502

{ # A context rule provides information about the context for an individual API

4503

# element.

4504

"provided": [ # A list of full type names of provided contexts.

4505

"A String",

4506

],

4507

"requested": [ # A list of full type names of requested contexts.

4508

"A String",

4509

],

4510

"selector": "A String", # Selects the methods to which this rule applies.

4511

#

4512

# Refer to selector for syntax details.

4513

},

4514

],

4515

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4516

"title": "A String", # The product title associated with this service.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4517

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4518

# with the same name as the service is automatically generated to service all

4519

# defined APIs.

4520

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4521

# A service may expose any number of endpoints, and all endpoints share the

4522

# same service configuration, such as quota configuration and monitoring

4523

# configuration.

4524

#

4525

# Example service configuration:

4526

#

4527

# name: library-example.googleapis.com

4528

# endpoints:

4529

# # Below entry makes 'google.example.library.v1.Library'

4530

# # API be served from endpoint address library-example.googleapis.com.

4531

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4532

# # it to decide whether the subsequent cross-origin request is

4533

# # allowed to proceed.

4534

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4535

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4536

"allowCors": True or False, # Allowing

4537

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4538

# cross-domain traffic, would allow the backends served from this endpoint to

4539

# receive and respond to HTTP OPTIONS requests. The response will be used by

4540

# the browser to determine whether the subsequent cross-origin request is

4541

# allowed to proceed.

4542

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4543

# please specify multiple google.api.Endpoint for each of the intented

4544

# alias.

4545

#

4546

# Additional names that this endpoint will be hosted on.

4547

"A String",

4548

],

4549

"features": [ # The list of features enabled on this endpoint.

4550

"A String",

4551

],

4552

"name": "A String", # The canonical name of this endpoint.

4553

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4558

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

4559

# only be used by whitelisted users.

4560

"authorization": { # Configuration of authorization. # Authorization configuration.

4561

#

4562

# This section determines the authorization provider, if unspecified, then no

4563

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

4570

"provider": "A String", # The name of the authorization provider, such as

4571

# firebaserules.googleapis.com.

4572

},

4573

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="list">list(serviceName=None, pageSize=None, pageToken=None, x__xgafv=None)</code>

4579

<pre>Lists the history of the service configuration for a managed service,

4580

from the newest to the oldest.

4581

4582

Args:

4583

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4584

for naming requirements. For example: `example.googleapis.com`. (required)

4585

pageSize: integer, The max number of items to include in the response list.

4586

pageToken: string, The token of the page to retrieve.

4587

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4594

4595

{ # Response message for ListServiceConfigs method.

4596

"nextPageToken": "A String", # The token of the next page of results.

4597

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4598

{ # `Service` is the root object of Google service configuration schema. It

4599

# describes basic information about a service, such as the name and the

4600

# title, and delegates other aspects to sub-sections. Each sub-section is

4601

# either a proto message or a repeated proto message that configures a

4602

# 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]

4607

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4608

# name: calendar.googleapis.com

4609

# title: Google Calendar API

4610

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4611

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4612

# authentication:

4613

# providers:

4614

# - id: google_calendar_auth

4615

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4616

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4617

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4618

# - selector: "*"

4619

# requirements:

4620

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4621

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4622

# service controller handles features like abuse, quota, billing, logging,

4623

# monitoring, etc.

4624

"environment": "A String", # The service control environment to use. If empty, no control plane

4625

# feature (like quota and billing) will be enabled.

4626

},

4627

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4628

# by the Service.monitoring and Service.logging configurations.

4629

{ # An object that describes the schema of a MonitoredResource object using a

4630

# type name and a set of labels. For example, the monitored resource

4631

# descriptor for Google Compute Engine VM instances has a type of

4632

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4633

# `"zone"` to identify particular VM instances.

4634

#

4635

# Different APIs can support different monitored resource types. APIs generally

4636

# provide a `list` method that returns the monitored resource descriptors used

4637

# by the API.

4638

"type": "A String", # Required. The monitored resource type. For example, the type

4639

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4640

# The maximum length of this value is 256 characters.

4641

"labels": [ # Required. A set of labels used to describe instances of this monitored

4642

# resource type. For example, an individual Google Cloud SQL database is

4643

# identified by values for the labels `"database_id"` and `"zone"`.

4644

{ # A description of a label.

4645

"valueType": "A String", # The type of data that can be assigned to the label.

4646

"description": "A String", # A human-readable description for the label.

4647

"key": "A String", # The label key.

4648

},

4649

],

4650

"displayName": "A String", # Optional. A concise name for the monitored resource type that might be

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

4651

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

4652

# without any article or other determiners. For example,

4653

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4654

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4655

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4656

# {type} is the value of the `type` field in this object and

4657

# {project_id} is a project ID that provides API-specific context for

4658

# accessing the type. APIs that do not use project information can use the

4659

# resource name format `"monitoredResourceDescriptors/{type}"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4660

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4661

# be used in documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4662

},

4663

],

4664

"logs": [ # Defines the logs used by this service.

4665

{ # A description of a log type. Example in YAML format:

4666

#

4667

# - name: library.googleapis.com/activity_history

4668

# description: The history of borrowing and returning library items.

4669

# display_name: Activity

4670

# labels:

4671

# - key: /customer_id

4672

# description: Identifier of a library customer

4673

"labels": [ # The set of labels that are available to describe a specific log entry.

4674

# Runtime requests that contain labels not specified here are

4675

# considered invalid.

4676

{ # A description of a label.

4677

"valueType": "A String", # The type of data that can be assigned to the label.

4678

"description": "A String", # A human-readable description for the label.

4679

"key": "A String", # The label key.

4680

},

4681

],

4682

"displayName": "A String", # The human-readable name for this log. This information appears on

4683

# the user interface and should be concise.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4684

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4685

# include the following characters: upper- and lower-case alphanumeric

4686

# characters [A-Za-z0-9], and punctuation characters including

4687

# slash, underscore, hyphen, period [/_-.].

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4688

"description": "A String", # A human-readable description of this log. This information appears in

4689

# the documentation and can contain details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4690

},

4691

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4692

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4693

# by the client for tracking purpose. If empty, the server may choose to

4694

# generate one instead.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4695

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4696

"rules": [ # A list of API backend rules that apply to individual API methods.

4697

#

4698

# **NOTE:** All service configuration rules follow "last one wins" order.

4699

{ # A backend rule provides configuration for an individual API element.

4700

"selector": "A String", # Selects the methods to which this rule applies.

4701

#

4702

# Refer to selector for syntax details.

4703

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4704

# default depends on the deployment context.

4705

"address": "A String", # The address of the API backend.

4706

},

4707

],

4708

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4709

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4710

#

4711

# The example below shows how to configure monitored resources and metrics

4712

# for monitoring. In the example, a monitored resource and two metrics are

4713

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4714

# to both producer and consumer projects, whereas the

4715

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4716

# consumer project.

4717

#

4718

# monitored_resources:

4719

# - type: library.googleapis.com/branch

4720

# labels:

4721

# - key: /city

4722

# description: The city where the library branch is located in.

4723

# - key: /name

4724

# description: The name of the branch.

4725

# metrics:

4726

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4731

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4736

# monitoring:

4737

# producer_destinations:

4738

# - monitored_resource: library.googleapis.com/branch

4739

# metrics:

4740

# - library.googleapis.com/book/returned_count

4741

# consumer_destinations:

4742

# - monitored_resource: library.googleapis.com/branch

4743

# metrics:

4744

# - library.googleapis.com/book/returned_count

4745

# - library.googleapis.com/book/overdue_count

4746

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4747

# There can be multiple producer destinations, each one must have a

4748

# different monitored resource type. A metric can be used in at most

4749

# one producer destination.

4750

{ # Configuration of a specific monitoring destination (the producer project

4751

# or the consumer project).

4752

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4753

# Service.monitored_resources section.

4754

"metrics": [ # Names of the metrics to report to this monitoring destination.

4755

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4761

# There can be multiple consumer destinations, each one must have a

4762

# different monitored resource type. A metric can be used in at most

4763

# one consumer destination.

4764

{ # Configuration of a specific monitoring destination (the producer project

4765

# or the consumer project).

4766

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4767

# Service.monitored_resources section.

4768

"metrics": [ # Names of the metrics to report to this monitoring destination.

4769

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4775

"systemParameters": { # ### System parameter configuration # System parameter configuration.

4776

#

4777

# A system parameter is a special kind of parameter defined by the API

4778

# system, not by an individual API. It is typically mapped to an HTTP header

4779

# and/or a URL query parameter. This configuration specifies which methods

4780

# change the names of the system parameters.

4781

"rules": [ # Define system parameters.

4782

#

4783

# The parameters defined here will override the default parameters

4784

# implemented by the system. If this field is missing from the service

4785

# config, default system parameters will be used. Default system parameters

4786

# and names is implementation-dependent.

4787

#

4788

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4796

#

4797

#

4798

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4803

# parameters:

4804

# - name: api_key

4805

# http_header: Api-Key1

4806

# - name: api_key

4807

# http_header: Api-Key2

4808

#

4809

# **NOTE:** All service configuration rules follow "last one wins" order.

4810

{ # Define a system parameter rule mapping system parameter definitions to

4811

# methods.

4812

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4813

# For a given method call, only one of them should be used. If multiple

4814

# names are used the behavior is implementation-dependent.

4815

# If none of the specified names are present the behavior is

4816

# parameter-dependent.

4817

{ # Define a parameter's name and location. The parameter may be passed as either

4818

# an HTTP header or a URL query parameter, and if both are passed the behavior

4819

# is implementation-dependent.

4820

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4821

# sensitive.

4822

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

4823

# insensitive.

4824

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

4825

},

4826

],

4827

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4828

# methods in all APIs.

4829

#

4830

# Refer to selector for syntax details.

4831

},

4832

],

4833

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4834

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4835

#

4836

# Example for an API targeted for external use:

4837

#

4838

# name: calendar.googleapis.com

4839

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4840

# providers:

4841

# - id: google_calendar_auth

4842

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4843

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4844

# rules:

4845

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4846

# requirements:

4847

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4848

"rules": [ # A list of authentication rules that apply to individual API methods.

4849

#

4850

# **NOTE:** All service configuration rules follow "last one wins" order.

4851

{ # Authentication rules for the service.

4852

#

4853

# By default, if a method has any authentication requirements, every request

4854

# must include a valid credential matching one of the requirements.

4855

# It's an error to include more than one kind of credential in a single

4856

# request.

4857

#

4858

# If a method doesn't have any auth requirements, request credentials will be

4859

# ignored.

4860

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4861

# there are scopes defined for "Read-only access to Google Calendar" and

4862

# "Access to Cloud Platform". Users can consent to a scope for an application,

4863

# giving it permission to access that data on their behalf.

4864

#

4865

# OAuth scope specifications should be fairly coarse grained; a user will need

4866

# to see and understand the text description of what your scope means.

4867

#

4868

# In most cases: use one or at most two OAuth scopes for an entire family of

4869

# products. If your product has multiple APIs, you should probably be sharing

4870

# the OAuth scope across all of those APIs.

4871

#

4872

# When you need finer grained OAuth consent screens: talk with your product

4873

# management about how developers will use them in practice.

4874

#

4875

# Please note that even though each of the canonical scopes is enough for a

4876

# request to be accepted and passed to the backend, a request can still fail

4877

# due to the backend requiring additional scopes or permissions.

4878

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4879

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4884

# https://www.googleapis.com/auth/calendar.read

4885

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4886

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

4887

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

4888

#

4889

# For requests without credentials, if the service control environment is

4890

# specified, each incoming request **must** be associated with a service

4891

# consumer. This can be done by passing an API key that belongs to a consumer

4892

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4893

"requirements": [ # Requirements for additional authentication providers.

4894

{ # User-defined authentication requirements, including support for

4895

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4896

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4901

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

4902

# implemented and accepted in all the runtime components.

4903

#

4904

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4905

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4906

# that are allowed to access. A JWT containing any of these audiences will

4907

# be accepted. When this setting is absent, only JWTs with audience

4908

# "https://Service_name/API_name"

4909

# will be accepted. For example, if no audiences are in the setting,

4910

# LibraryService API will only accept JWTs with the following audience

4911

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4916

# bookstore_web.apps.googleusercontent.com

4917

},

4918

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4919

"selector": "A String", # Selects the methods to which this rule applies.

4920

#

4921

# Refer to selector for syntax details.

4922

},

4923

],

4924

"providers": [ # Defines a set of authentication providers that a service supports.

4925

{ # Configuration for an anthentication provider, including support for

4926

# [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]

4927

"audiences": "A String", # The list of JWT

4928

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4929

# that are allowed to access. A JWT containing any of these audiences will

4930

# be accepted. When this setting is absent, only JWTs with audience

4931

# "https://Service_name/API_name"

4932

# will be accepted. For example, if no audiences are in the setting,

4933

# LibraryService API will only accept JWTs with the following audience

4934

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4939

# bookstore_web.apps.googleusercontent.com

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

4940

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4941

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4942

# Optional if the key set document:

4943

# - can be retrieved from

4944

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4945

# of the issuer.

4946

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4947

#

4948

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4949

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4950

# `AuthRequirement.provider_id`.

4951

#

4952

# Example: "bookstore_auth".

4953

"issuer": "A String", # Identifies the principal that issued the JWT. See

4954

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4955

# Usually a URL or an email address.

4956

#

4957

# Example: https://securetoken.google.com

4958

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4963

"rules": [ # A list of usage rules that apply to individual API methods.

4964

#

4965

# **NOTE:** All service configuration rules follow "last one wins" order.

4966

{ # Usage configuration rules for the service.

4967

#

4968

# NOTE: Under development.

4969

#

4970

#

4971

# Use this rule to configure unregistered calls for the service. Unregistered

4972

# calls are calls that do not contain consumer project identity.

4973

# (Example: calls that do not contain an API key).

4974

# By default, API methods do not allow unregistered calls, and each method call

4975

# must be identified by a consumer project identity. Use this rule to

4976

# allow/disallow unregistered calls.

4977

#

4978

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4984

#

4985

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4990

# allow_unregistered_calls: true

4991

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4992

# methods in all APIs.

4993

#

4994

# Refer to selector for syntax details.

4995

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4996

},

4997

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

4998

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4999

# service producer.

5000

#

5001

# Google Service Management currently only supports

5002

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

5003

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

5004

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

5005

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5006

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

5007

# service. Each requirement is of the form <service.name>/<requirement-id>;

5008

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

5013

# influence interpretation of the configuration, for example, to

5014

# determine defaults. This is documented together with applicable

5015

# options. The current default for the config version itself is `3`.

5016

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

5017

# Members of this project can manage the service configuration,

5018

# manage consumption of the service, etc.

5019

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

5020

# HttpRule, each specifying the mapping of an RPC method

5021

# to one or more HTTP REST API methods.

5022

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

5023

#

5024

# **NOTE:** All service configuration rules follow "last one wins" order.

5025

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

5026

# REST APIs. The mapping determines what portions of the request

5027

# message are populated from the path, query parameters, or body of

5028

# the HTTP request. The mapping is typically specified as an

5029

# `google.api.http` annotation, see "google/api/annotations.proto"

5030

# for details.

5031

#

5032

# The mapping consists of a field specifying the path template and

5033

# method kind. The path template can refer to fields in the request

5034

# message, as in the example below which describes a REST GET

5035

# operation on a resource collection of messages:

5036

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5037

#

5038

# service Messaging {

5039

# rpc GetMessage(GetMessageRequest) returns (Message) {

5040

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

5041

# }

5042

# }

5043

# message GetMessageRequest {

5044

# message SubMessage {

5045

# string subfield = 1;

5046

# }

5047

# string message_id = 1; // mapped to the URL

5048

# SubMessage sub = 2; // `sub.subfield` is url-mapped

5049

# }

5050

# message Message {

5051

# string text = 1; // content of the resource

5052

# }

5053

#

5054

# The same http annotation can alternatively be expressed inside the

5055

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

5060

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5061

#

5062

# This definition enables an automatic, bidrectional mapping of HTTP

5063

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

5068

#

5069

# In general, not only fields but also field paths can be referenced

5070

# from a path pattern. Fields mapped to the path pattern cannot be

5071

# repeated and must have a primitive (non-message) type.

5072

#

5073

# Any fields in the request message which are not bound by the path

5074

# pattern automatically become (optional) HTTP query

5075

# parameters. Assume the following definition of the request message:

5076

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5077

#

5078

# message GetMessageRequest {

5079

# message SubMessage {

5080

# string subfield = 1;

5081

# }

5082

# string message_id = 1; // mapped to the URL

5083

# int64 revision = 2; // becomes a parameter

5084

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

5085

# }

5086

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5087

#

5088

# 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"))`

5093

#

5094

# Note that fields which are mapped to HTTP parameters must have a

5095

# primitive type or a repeated primitive type. Message types are not

5096

# allowed. In the case of a repeated type, the parameter can be

5097

# repeated in the URL, as in `...?param=A&param=B`.

5098

#

5099

# For HTTP method kinds which allow a request body, the `body` field

5100

# specifies the mapping. Consider a REST update method on the

5101

# message resource collection:

5102

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5103

#

5104

# service Messaging {

5105

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

5106

# option (google.api.http) = {

5107

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

5113

# string message_id = 1; // mapped to the URL

5114

# Message message = 2; // mapped to the body

5115

# }

5116

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5117

#

5118

# The following HTTP JSON to RPC mapping is enabled, where the

5119

# representation of the JSON in the request body is determined by

5120

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

5125

#

5126

# The special name `*` can be used in the body mapping to define that

5127

# every field not bound by the path template should be mapped to the

5128

# request body. This enables the following alternative definition of

5129

# the update method:

5130

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5131

# service Messaging {

5132

# rpc UpdateMessage(Message) returns (Message) {

5133

# option (google.api.http) = {

5134

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

5141

# string text = 2;

5142

# }

5143

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5144

#

5145

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

5150

#

5151

# Note that when using `*` in the body mapping, it is not possible to

5152

# have HTTP parameters, as all fields not bound by the path end in

5153

# the body. This makes this option more rarely used in practice of

5154

# defining REST APIs. The common usage of `*` is in custom methods

5155

# which don't use the URL at all for transferring data.

5156

#

5157

# It is possible to define multiple HTTP methods for one RPC by using

5158

# the `additional_bindings` option. Example:

5159

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5160

# service Messaging {

5161

# rpc GetMessage(GetMessageRequest) returns (Message) {

5162

# option (google.api.http) = {

5163

# get: "/v1/messages/{message_id}"

5164

# additional_bindings {

5165

# get: "/v1/users/{user_id}/messages/{message_id}"

5166

# }

5167

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5168

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5169

# }

5170

# message GetMessageRequest {

5171

# string message_id = 1;

5172

# string user_id = 2;

5173

# }

5174

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5175

#

5176

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

5182

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

5183

#

5184

# # Rules for HTTP mapping

5185

#

5186

# The rules for mapping HTTP path, query parameters, and body fields

5187

# to the request message are as follows:

5188

#

5189

# 1. The `body` field specifies either `*` or a field path, or is

5190

# omitted. If omitted, it assumes there is no HTTP body.

5191

# 2. Leaf fields (recursive expansion of nested messages in the

5192

# request) can be classified into three types:

5193

# (a) Matched in the URL template.

5194

# (b) Covered by body (if body is `*`, everything except (a) fields;

5195

# else everything under the body field)

5196

# (c) All other fields.

5197

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

5198

# 4. Any body sent with an HTTP request can contain only (b) fields.

5199

#

5200

# The syntax of the path template is as follows:

5201

#

5202

# Template = "/" Segments [ Verb ] ;

5203

# Segments = Segment { "/" Segment } ;

5204

# Segment = "*" | "**" | LITERAL | Variable ;

5205

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5206

# FieldPath = IDENT { "." IDENT } ;

5207

# Verb = ":" LITERAL ;

5208

#

5209

# The syntax `*` matches a single path segment. It follows the semantics of

5210

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

5211

# Expansion.

5212

#

5213

# The syntax `**` matches zero or more path segments. It follows the semantics

5214

# 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]

5215

# 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]

5216

#

5217

# The syntax `LITERAL` matches literal text in the URL path.

5218

#

5219

# The syntax `Variable` matches the entire path as specified by its template;

5220

# this nested template must not contain further variables. If a variable

5221

# matches a single path segment, its template may be omitted, e.g. `{var}`

5222

# is equivalent to `{var=*}`.

5223

#

5224

# NOTE: the field paths in variables and in the `body` must not refer to

5225

# repeated fields or map fields.

5226

#

5227

# Use CustomHttpPattern to specify any HTTP method that is not included in the

5228

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

5229

# a given URL path rule. The wild-card rule is useful for services that provide

5230

# content to Web (HTML) clients.

5231

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

5232

# `*` for mapping all fields not captured by the path pattern to the HTTP

5233

# 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]

5234

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5235

"get": "A String", # Used for listing and getting information about resources.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5236

"mediaDownload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for bytestream methods.

5237

# For media support, add instead [][google.bytestream.RestByteStream] as an

5238

# API to your configuration.

5239

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

5240

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5241

"enabled": True or False, # Whether download is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5242

"downloadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

5243

#

5244

# Specify name of the download service if one is used for download.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5245

},

5246

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

5247

# not contain an `additional_bindings` field themselves (that is,

5248

# the nesting may only be one level deep).

5249

# Object with schema name: HttpRule

5250

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5251

"mediaUpload": { # Use this only for Scotty Requests. Do not use this for media support using # Use this only for Scotty Requests. Do not use this for media support using

5252

# Bytestream, add instead

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5253

# [][google.bytestream.RestByteStream] as an API to your

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5254

# configuration for Bytestream methods.

5255

# Bytestream, add instead [][google.bytestream.RestByteStream] as an API to

5256

# your configuration for Bytestream methods.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5257

"enabled": True or False, # Whether upload is enabled.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5258

"uploadService": "A String", # DO NOT USE THIS FIELD UNTIL THIS WARNING IS REMOVED.

5259

#

5260

# Specify name of the upload service if one is used for upload.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5261

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5262

"selector": "A String", # Selects methods to which this rule applies.

5263

#

5264

# Refer to selector for syntax details.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5265

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

5266

# response. Other response fields are ignored. This field is optional. When

5267

# not set, the response message will be used as HTTP body of response.

5268

# NOTE: the referred field must be not a repeated field and must be present

5269

# at the top-level of response message type.

5270

"put": "A String", # Used for updating a resource.

5271

"patch": "A String", # Used for updating a resource.

5272

"post": "A String", # Used for creating a resource.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5273

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

5274

"path": "A String", # The path matched by this custom verb.

5275

"kind": "A String", # The name of this custom HTTP verb.

5276

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5277

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

5282

# of the google.protobuf.Api needs to be provided by the configuration

5283

# author, as the remaining fields will be derived from the IDL during the

5284

# normalization process. It is an error to specify an API interface here

5285

# which cannot be resolved against the associated IDL files.

5286

{ # Api is a light-weight descriptor for a protocol buffer service.

5287

"methods": [ # The methods of this api, in unspecified order.

5288

{ # Method represents a method of an api.

5289

"name": "A String", # The simple name of this method.

5290

"requestStreaming": True or False, # If true, the request is streamed.

5291

"responseTypeUrl": "A String", # The URL of the output message type.

5292

"requestTypeUrl": "A String", # A URL of the input message type.

5293

"responseStreaming": True or False, # If true, the response is streamed.

5294

"syntax": "A String", # The source syntax of this method.

5295

"options": [ # Any metadata attached to the method.

5296

{ # A protocol buffer option, which can be attached to a message, field,

5297

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5298

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5299

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5300

# For custom options, it should be the fully-qualified name. For example,

5301

# `"google.api.http"`.

5302

"value": { # The option's value packed in an Any message. If the value is a primitive,

5303

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5304

# should be used. If the value is an enum, it should be stored as an int32

5305

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5306

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

"sourceContext": { # `SourceContext` represents information about the source of a # Source context for the protocol buffer service represented by this

5313

# message.

5314

# protobuf element, like the file in which it is defined.

5315

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5316

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5317

},

5318

"mixins": [ # Included APIs. See Mixin.

5319

{ # Declares an API to be included in this API. The including API must

5320

# redeclare all the methods from the included API, but documentation

5321

# and options are inherited as follows:

5322

#

5323

# - If after comment and whitespace stripping, the documentation

5324

# string of the redeclared method is empty, it will be inherited

5325

# from the original method.

5326

#

5327

# - Each annotation belonging to the service config (http,

5328

# visibility) which is not set in the redeclared method will be

5329

# inherited.

5330

#

5331

# - If an http annotation is inherited, the path pattern will be

5332

# modified as follows. Any version prefix will be replaced by the

5333

# version of the including API plus the root path if specified.

5334

#

5335

# Example of a simple mixin:

5336

#

5337

# package google.acl.v1;

5338

# service AccessControl {

5339

# // Get the underlying ACL object.

5340

# rpc GetAcl(GetAclRequest) returns (Acl) {

5341

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

5346

# service Storage {

5347

# // rpc GetAcl(GetAclRequest) returns (Acl);

5348

#

5349

# // Get a data record.

5350

# rpc GetData(GetDataRequest) returns (Data) {

5351

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

5356

#

5357

# apis:

5358

# - name: google.storage.v2.Storage

5359

# mixins:

5360

# - name: google.acl.v1.AccessControl

5361

#

5362

# The mixin construct implies that all methods in `AccessControl` are

5363

# also declared with same name and request/response types in

5364

# `Storage`. A documentation generator or annotation processor will

5365

# see the effective `Storage.GetAcl` method after inherting

5366

# documentation and annotations as follows:

5367

#

5368

# service Storage {

5369

# // Get the underlying ACL object.

5370

# rpc GetAcl(GetAclRequest) returns (Acl) {

5371

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

5377

#

5378

# If the `root` field in the mixin is specified, it should be a

5379

# relative path under which inherited HTTP paths are placed. Example:

5380

#

5381

# apis:

5382

# - name: google.storage.v2.Storage

5383

# mixins:

5384

# - name: google.acl.v1.AccessControl

5385

# root: acls

5386

#

5387

# This implies the following inherited HTTP annotation:

5388

#

5389

# service Storage {

5390

# // Get the underlying ACL object.

5391

# rpc GetAcl(GetAclRequest) returns (Acl) {

5392

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

5397

# are rooted.

5398

"name": "A String", # The fully qualified name of the API which is included.

5399

},

5400

],

5401

"syntax": "A String", # The source syntax of the service.

5402

"version": "A String", # A version string for this api. If specified, must have the form

5403

# `major-version.minor-version`, as in `1.10`. If the minor version

5404

# is omitted, it defaults to zero. If the entire version field is

5405

# empty, the major version is derived from the package name, as

5406

# outlined below. If the field is not empty, the version in the

5407

# package name will be verified to be consistent with what is

5408

# provided here.

5409

#

5410

# The versioning schema uses [semantic

5411

# versioning](http://semver.org) where the major version number

5412

# indicates a breaking change and the minor version an additive,

5413

# non-breaking change. Both version numbers are signals to users

5414

# what to expect from different versions, and should be carefully

5415

# chosen based on the product plan.

5416

#

5417

# The major version is also reflected in the package name of the

5418

# API, which must end in `v<major-version>`, as in

5419

# `google.feature.v1`. For major versions 0 and 1, the suffix can

5420

# be omitted. Zero major versions must only be used for

5421

# experimental, none-GA apis.

5422

"options": [ # Any metadata attached to the API.

5423

{ # A protocol buffer option, which can be attached to a message, field,

5424

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5425

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5426

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5427

# For custom options, it should be the fully-qualified name. For example,

5428

# `"google.api.http"`.

5429

"value": { # The option's value packed in an Any message. If the value is a primitive,

5430

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5431

# should be used. If the value is an enum, it should be stored as an int32

5432

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5433

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # The fully qualified name of this api, including package name

5438

# followed by the api's simple name.

5439

},

5440

],

5441

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5442

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5450

# - google.foo.v1.AnotherError

5451

"rules": [ # The list of custom error rules that apply to individual API messages.

5452

#

5453

# **NOTE:** All service configuration rules follow "last one wins" order.

5454

{ # A custom error rule.

5455

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5456

# objects of this type will be filtered when they appear in error payload.

5457

"selector": "A String", # Selects messages to which this rule applies.

5458

#

5459

# Refer to selector for syntax details.

5460

},

5461

],

5462

"types": [ # The list of custom error detail types, e.g. 'google.foo.v1.CustomError'.

"A String",

],

},

"visibility": { # `Visibility` defines restrictions for the visibility of service # API visibility configuration.

5467

# elements. Restrictions are specified using visibility labels

5468

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

5469

#

5470

# Users and projects can have access to more than one visibility label. The

5471

# effective visibility for multiple labels is the union of each label's

5472

# elements, plus any unrestricted elements.

5473

#

5474

# If an element and its parents have no restrictions, visibility is

5475

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5482

# restriction: TRUSTED_TESTER

5483

# - selector: google.calendar.Calendar.Delegate

5484

# restriction: GOOGLE_INTERNAL

5485

#

5486

# Here, all methods are publicly visible except for the restricted methods

5487

# EnhancedSearch and Delegate.

5488

"rules": [ # A list of visibility rules that apply to individual API elements.

5489

#

5490

# **NOTE:** All service configuration rules follow "last one wins" order.

5491

{ # A visibility rule provides visibility configuration for an individual API

5492

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5493

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

5494

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5495

#

5496

# If a rule has multiple labels, removing one of the labels but not all of

5497

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5504

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

5505

#

5506

# Removing GOOGLE_INTERNAL from this restriction will break clients that

5507

# rely on this method and only had access to it through GOOGLE_INTERNAL.

5508

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

5509

#

5510

# 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]

5515

{ # Defines a metric type and its schema. Once a metric descriptor is created,

5516

# deleting or altering it stops data collection and makes the metric type's

5517

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5518

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5519

# Use sentence case without an ending period, for example "Request count".

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5520

"name": "A String", # The resource name of the metric descriptor. Depending on the

5521

# implementation, the name typically includes: (1) the parent resource name

5522

# that defines the scope of the metric type or of its data; and (2) the

5523

# metric's URL-encoded type, which also appears in the `type` field of this

5524

# descriptor. For example, following is the resource name of a custom

5525

# metric within the GCP project `my-project-id`:

5526

#

5527

# "projects/my-project-id/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5528

"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]

5529

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5530

"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]

5531

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5532

"labels": [ # The set of labels that can be used to describe a specific

5533

# instance of this metric type. For example, the

5534

# `appengine.googleapis.com/http/server/response_latencies` metric

5535

# type has a label for the HTTP response code, `response_code`, so

5536

# you can look at latencies for successful responses or just

5537

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5538

{ # A description of a label.

5539

"valueType": "A String", # The type of data that can be assigned to the label.

5540

"description": "A String", # A human-readable description for the label.

5541

"key": "A String", # The label key.

5542

},

5543

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5544

"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^]

5545

# URL-encoded. All user-defined custom metric types have the DNS name

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5546

# `custom.googleapis.com`. Metric types should use a natural hierarchical

5547

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5548

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5549

# "custom.googleapis.com/invoice/paid/amount"

5550

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5551

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

5552

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

5553

# supported units are a subset of [The Unified Code for Units of

5554

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5555

#

5556

# **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)

5571

# * `P` peta (10**15)

5572

# * `E` exa (10**18)

5573

# * `Z` zetta (10**21)

5574

# * `Y` yotta (10**24)

5575

# * `m` milli (10**-3)

5576

# * `u` micro (10**-6)

5577

# * `n` nano (10**-9)

5578

# * `p` pico (10**-12)

5579

# * `f` femto (10**-15)

5580

# * `a` atto (10**-18)

5581

# * `z` zepto (10**-21)

5582

# * `y` yocto (10**-24)

5583

# * `Ki` kibi (2**10)

5584

# * `Mi` mebi (2**20)

5585

# * `Gi` gibi (2**30)

5586

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5591

#

5592

# The grammar also includes these connectors:

5593

#

5594

# * `/` division (as an infix operator, e.g. `1/s`).

5595

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5596

#

5597

# The grammar for a unit is as follows:

5598

#

5599

# Expression = Component { "." Component } { "/" Component } ;

5600

#

5601

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5611

# equivalent to `1` if it is used alone. For examples,

5612

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5613

# * `NAME` is a sequence of non-blank printable ASCII characters not

5614

# containing '{' or '}'.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5615

"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]

5616

},

5617

],

5618

"enums": [ # A list of all enum types included in this API service. Enums

5619

# referenced directly or indirectly by the `apis` are automatically

5620

# included. Enums which are not referenced but shall be included

5621

# should be listed here by name. Example:

5622

#

5623

# enums:

5624

# - name: google.someapi.v1.SomeEnum

5625

{ # Enum type definition.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5626

"syntax": "A String", # The source syntax.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5627

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5628

# protobuf element, like the file in which it is defined.

5629

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5630

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5631

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5632

"options": [ # Protocol buffer options.

5633

{ # A protocol buffer option, which can be attached to a message, field,

5634

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5635

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5636

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5637

# For custom options, it should be the fully-qualified name. For example,

5638

# `"google.api.http"`.

5639

"value": { # The option's value packed in an Any message. If the value is a primitive,

5640

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5641

# should be used. If the value is an enum, it should be stored as an int32

5642

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5643

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5648

"enumvalue": [ # Enum value definitions.

5649

{ # Enum value definition.

5650

"options": [ # Protocol buffer options.

5651

{ # A protocol buffer option, which can be attached to a message, field,

5652

# enumeration, etc.

5653

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5654

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5655

# For custom options, it should be the fully-qualified name. For example,

5656

# `"google.api.http"`.

5657

"value": { # The option's value packed in an Any message. If the value is a primitive,

5658

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5659

# should be used. If the value is an enum, it should be stored as an int32

5660

# value using the google.protobuf.Int32Value type.

5661

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"number": 42, # Enum value number.

5666

"name": "A String", # Enum value name.

5667

},

5668

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5669

},

5670

],

5671

"types": [ # A list of all proto message types included in this API service.

5672

# Types referenced directly or indirectly by the `apis` are

5673

# automatically included. Messages which are not referenced but

5674

# shall be included, such as types used by the `google.protobuf.Any` type,

5675

# should be listed here by name. Example:

5676

#

5677

# types:

5678

# - name: google.protobuf.Int32

5679

{ # A protocol buffer message type.

5680

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5681

"A String",

5682

],

5683

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5684

"fields": [ # The list of fields.

5685

{ # A single field of a message type.

5686

"kind": "A String", # The field type.

5687

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5688

# types. The first type has index 1; zero means the type is not in the list.

5689

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5690

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5691

"name": "A String", # The field name.

5692

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5693

"jsonName": "A String", # The field JSON name.

5694

"number": 42, # The field number.

5695

"cardinality": "A String", # The field cardinality.

5696

"options": [ # The protocol buffer options.

5697

{ # A protocol buffer option, which can be attached to a message, field,

5698

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5699

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5700

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5701

# For custom options, it should be the fully-qualified name. For example,

5702

# `"google.api.http"`.

5703

"value": { # The option's value packed in an Any message. If the value is a primitive,

5704

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5705

# should be used. If the value is an enum, it should be stored as an int32

5706

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5707

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5712

},

5713

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5714

"syntax": "A String", # The source syntax.

5715

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5716

# protobuf element, like the file in which it is defined.

5717

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5718

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5719

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5720

"options": [ # The protocol buffer options.

5721

{ # A protocol buffer option, which can be attached to a message, field,

5722

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5723

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5724

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5725

# For custom options, it should be the fully-qualified name. For example,

5726

# `"google.api.http"`.

5727

"value": { # The option's value packed in an Any message. If the value is a primitive,

5728

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5729

# should be used. If the value is an enum, it should be stored as an int32

5730

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5731

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5737

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5738

#

5739

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5740

# producer and consumer projects. In the example, the `activity_history`

5741

# log is sent to both the producer and consumer projects, whereas the

5742

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5743

#

5744

# monitored_resources:

5745

# - type: library.googleapis.com/branch

5746

# labels:

5747

# - key: /city

5748

# description: The city where the library branch is located in.

5749

# - key: /name

5750

# description: The name of the branch.

5751

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5752

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5753

# labels:

5754

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5755

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5756

# logging:

5757

# producer_destinations:

5758

# - monitored_resource: library.googleapis.com/branch

5759

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5760

# - activity_history

5761

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5762

# consumer_destinations:

5763

# - monitored_resource: library.googleapis.com/branch

5764

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5765

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5766

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5767

# There can be multiple producer destinations, each one must have a

5768

# different monitored resource type. A log can be used in at most

5769

# one producer destination.

5770

{ # Configuration of a specific logging destination (the producer project

5771

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5772

"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]

5773

# Service.monitored_resources section.

5774

"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]

5775

# be defined in the Service.logs section. If the log name is

5776

# not a domain scoped name, it will be automatically prefixed with

5777

# 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.

5783

# There can be multiple consumer destinations, each one must have a

5784

# different monitored resource type. A log can be used in at most

5785

# one consumer destination.

5786

{ # Configuration of a specific logging destination (the producer project

5787

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5788

"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]

5789

# Service.monitored_resources section.

5790

"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]

5791

# be defined in the Service.logs section. If the log name is

5792

# not a domain scoped name, it will be automatically prefixed with

5793

# 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,

5800

# e.g. `calendar.googleapis.com`.

5801

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5802

#

5803

# Example:

5804

# <pre><code>documentation:

5805

# summary: >

5806

# The Google Calendar API gives access

5807

# to most calendar features.

5808

# pages:

5809

# - name: Overview

5810

# content: (== include google/foo/overview.md ==)

5811

# - name: Tutorial

5812

# content: (== include google/foo/tutorial.md ==)

5813

# subpages;

5814

# - name: Java

5815

# content: (== include google/foo/tutorial_java.md ==)

5816

# rules:

5817

# - selector: google.calendar.Calendar.Get

5818

# description: >

5819

# ...

5820

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5825

# standard markdown features, definition lists, tables and fenced

5826

# code blocks are supported. Section headers can be provided and are

5827

# interpreted relative to the section nesting of the context where

5828

# a documentation fragment is embedded.

5829

#

5830

# Documentation from the IDL is merged with documentation defined

5831

# via the config at normalization time, where documentation provided

5832

# by config rules overrides IDL provided.

5833

#

5834

# A number of constructs specific to the API platform are supported

5835

# in documentation text.

5836

#

5837

# In order to reference a proto element, the following

5838

# notation can be used:

5839

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5840

# To override the display text used for the link, this can be used:

5841

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5842

# Text can be excluded from doc using the following notation:

5843

# <pre><code>(-- internal comment --)</code></pre>

5844

# Comments can be made conditional using a visibility label. The below

5845

# text will be only rendered if the `BETA` label is available:

5846

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5847

# A few directives are available in documentation. Note that

5848

# directives must appear on a single line to be properly

5849

# identified. The `include` directive includes a markdown file from

5850

# an external source:

5851

# <pre><code>(== include path/to/file ==)</code></pre>

5852

# The `resource_for` directive marks a message to be the resource of

5853

# a collection in REST view. If it is not specified, tools attempt

5854

# to infer the resource from the operations in a collection:

5855

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5856

# The directive `suppress_warning` does not directly affect documentation

5857

# and is documented together with service config validation.

5858

"rules": [ # A list of documentation rules that apply to individual API elements.

5859

#

5860

# **NOTE:** All service configuration rules follow "last one wins" order.

5861

{ # A documentation rule provides information about individual API elements.

5862

"description": "A String", # Description of the selected API(s).

5863

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5864

# element is marked as `deprecated`.

5865

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5866

# qualified name of the element which may end in "*", indicating a wildcard.

5867

# Wildcards are only allowed at the end and for a whole component of the

5868

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5869

# specify a default for all applicable elements, the whole pattern "*"

5870

# is used.

5871

},

5872

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5873

"documentationRootUrl": "A String", # The URL to the root of documentation.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5874

"summary": "A String", # A short summary of what the service does. Can only be provided by

5875

# plain text.

5876

"pages": [ # The top level pages for the documentation set.

5877

{ # Represents a documentation page. A page can contain subpages to represent

5878

# nested documentation set structure.

5879

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5880

# to include content from a Markdown file.

5881

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5882

# honored in the generated docset.

5883

# Object with schema name: Page

5884

],

5885

"name": "A String", # The name of the page. It will be used as an identity of the page to

5886

# generate URI of the page, text of the link to this page in navigation,

5887

# etc. The full page name (start from the root page name to this page

5888

# concatenated with `.`) can be used as reference to the page in your

5889

# documentation. For example:

5890

# <pre><code>pages:

5891

# - name: Tutorial

5892

# content: (== include tutorial.md ==)

5893

# subpages:

5894

# - name: Java

5895

# content: (== include tutorial_java.md ==)

5896

# </code></pre>

5897

# You can reference `Java` page using Markdown reference link syntax:

5898

# `Java`.

5899

},

5900

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5901

"overview": "A String", # Declares a single overview page. For example:

5902

# <pre><code>documentation:

5903

# summary: ...

5904

# overview: (== include overview.md ==)

5905

# </code></pre>

5906

# This is a shortcut for the following declaration (using pages style):

5907

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5912

# </code></pre>

5913

# Note: you cannot specify both `overview` field and `pages` field.

5914

},

5915

"sourceInfo": { # Source information used to create a Service Config # Output only. The source information for this configuration if available.

5916

"sourceFiles": [ # All files used during config generation.

5917

{

5918

"a_key": "", # Properties of the object. Contains field @type with type URL.

5919

},

5920

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5921

},

5922

"systemTypes": [ # A list of all proto message types included in this API service.

5923

# It serves similar purpose as [google.api.Service.types], except that

5924

# these types are not needed by user-defined APIs. Therefore, they will not

5925

# show up in the generated discovery doc. This field should only be used

5926

# to define system APIs in ESF.

5927

{ # A protocol buffer message type.

5928

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5929

"A String",

5930

],

5931

"name": "A String", # The fully qualified message name.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5932

"fields": [ # The list of fields.

5933

{ # A single field of a message type.

5934

"kind": "A String", # The field type.

5935

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5936

# types. The first type has index 1; zero means the type is not in the list.

5937

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5938

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5939

"name": "A String", # The field name.

5940

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5941

"jsonName": "A String", # The field JSON name.

5942

"number": 42, # The field number.

5943

"cardinality": "A String", # The field cardinality.

5944

"options": [ # The protocol buffer options.

5945

{ # A protocol buffer option, which can be attached to a message, field,

5946

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5947

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5948

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5949

# For custom options, it should be the fully-qualified name. For example,

5950

# `"google.api.http"`.

5951

"value": { # The option's value packed in an Any message. If the value is a primitive,

5952

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5953

# should be used. If the value is an enum, it should be stored as an int32

5954

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5955

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5960

},

5961

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

5962

"syntax": "A String", # The source syntax.

5963

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5964

# protobuf element, like the file in which it is defined.

5965

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5966

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5967

},

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5968

"options": [ # The protocol buffer options.

5969

{ # A protocol buffer option, which can be attached to a message, field,

5970

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame]

5971

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5972

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5973

# For custom options, it should be the fully-qualified name. For example,

5974

# `"google.api.http"`.

5975

"value": { # The option's value packed in an Any message. If the value is a primitive,

5976

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5977

# should be used. If the value is an enum, it should be stored as an int32

5978

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5979

"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

5994

# - google.rpc.context.OriginContext

5995

#

5996

# The above specifies that all methods in the API request

5997

# `google.rpc.context.ProjectContext` and

5998

# `google.rpc.context.OriginContext`.

5999

#

6000

# Available context types are defined in package

6001

# `google.rpc.context`.

6002

"rules": [ # A list of RPC context rules that apply to individual API methods.

6003

#

6004

# **NOTE:** All service configuration rules follow "last one wins" order.

6005

{ # A context rule provides information about the context for an individual API

6006

# element.

6007

"provided": [ # A list of full type names of provided contexts.

6008

"A String",

6009

],

6010

"requested": [ # A list of full type names of requested contexts.

6011

"A String",

6012

],

6013

"selector": "A String", # Selects the methods to which this rule applies.

6014

#

6015

# Refer to selector for syntax details.

6016

},

6017

],

6018

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

6019

"title": "A String", # The product title associated with this service.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6020

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

6021

# with the same name as the service is automatically generated to service all

6022

# defined APIs.

6023

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

6024

# A service may expose any number of endpoints, and all endpoints share the

6025

# same service configuration, such as quota configuration and monitoring

6026

# configuration.

6027

#

6028

# Example service configuration:

6029

#

6030

# name: library-example.googleapis.com

6031

# endpoints:

6032

# # Below entry makes 'google.example.library.v1.Library'

6033

# # API be served from endpoint address library-example.googleapis.com.

6034

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

6035

# # it to decide whether the subsequent cross-origin request is

6036

# # allowed to proceed.

6037

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6038

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

6039

"allowCors": True or False, # Allowing

6040

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

6041

# cross-domain traffic, would allow the backends served from this endpoint to

6042

# receive and respond to HTTP OPTIONS requests. The response will be used by

6043

# the browser to determine whether the subsequent cross-origin request is

6044

# allowed to proceed.

6045

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

6046

# please specify multiple google.api.Endpoint for each of the intented

6047

# alias.

6048

#

6049

# Additional names that this endpoint will be hosted on.

6050

"A String",

6051

],

6052

"features": [ # The list of features enabled on this endpoint.

6053

"A String",

6054

],

6055

"name": "A String", # The canonical name of this endpoint.

6056

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

6061

"experimental": { # Experimental service configuration. These configuration options can # Experimental configuration.

6062

# only be used by whitelisted users.

6063

"authorization": { # Configuration of authorization. # Authorization configuration.

6064

#

6065

# This section determines the authorization provider, if unspecified, then no

6066

# authorization check will be done.

#

# Example:

#

# experimental:

# authorization:

# provider: firebaserules.googleapis.com

6073

"provider": "A String", # The name of the authorization provider, such as

6074

# firebaserules.googleapis.com.

6075

},

6076

},

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>

6084

<pre>Retrieves the next page of results.

6085

6086

Args:

6087

previous_request: The request for the previous page. (required)

6088

previous_response: The response from the request for the previous page. (required)

6089

6090

Returns:

6091

A request object that you can call 'execute()' on to request the next

6092

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="submit">submit(serviceName=None, body, x__xgafv=None)</code>

6098

<pre>Creates a new service configuration (version) for a managed service based

6099

on

6100

user-supplied configuration source files (for example: OpenAPI

6101

Specification). This method stores the source configurations as well as the

6102

generated service configuration. To rollout the service configuration to

6103

other services,

6104

please call CreateServiceRollout.

6105

6106

Operation<response: SubmitConfigSourceResponse>

6107

6108

Args:

6109

serviceName: string, The name of the service. See the [overview](/service-management/overview)

6110

for naming requirements. For example: `example.googleapis.com`. (required)

6111

body: object, The request body. (required)

6112

The object takes the form of:

6113

6114

{ # Request message for SubmitConfigSource method.

6115

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

6116

# `google.api.Service` configuration based on the `ConfigSource` provided,

6117

# but the generated config and the sources will NOT be persisted.

6118

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

6119

# defined by `google.api.Service`.

6120

"files": [ # Set of source configuration files that are used to generate a service

6121

# configuration (`google.api.Service`).

6122

{ # Generic specification of a source configuration file

6123

"fileContents": "A String", # The bytes that constitute the file.

6124

"fileType": "A String", # The type of configuration file this represents.

6125

"filePath": "A String", # The file name of the configuration file (full or relative path).

6126

},

6127

],

6128

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

6129

# by the client for tracking purpose. If empty, the server may choose to

6130

# 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:

6141

6142

{ # This resource represents a long-running operation that is the result of a

6143

# network API call.

6144

"metadata": { # Service-specific metadata associated with the operation. It typically

6145

# contains progress information and common metadata such as create time.

6146

# Some services might not provide such metadata. Any method that returns a

6147

# long-running operation should document the metadata type, if any.

6148

"a_key": "", # Properties of the object. Contains field @type with type URL.

6149

},

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6150

"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]

6151

# programming environments, including REST APIs and RPC APIs. It is used by

6152

# [gRPC](https://github.com/grpc). The error model is designed to be:

6153

#

6154

# - Simple to use and understand for most users

6155

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

6160

# and error details. The error code should be an enum value of

6161

# google.rpc.Code, but it may accept additional error codes if needed. The

6162

# error message should be a developer-facing English message that helps

6163

# developers *understand* and *resolve* the error. If a localized user-facing

6164

# error message is needed, put the localized message in the error details or

6165

# localize it in the client. The optional error details may contain arbitrary

6166

# information about the error. There is a predefined set of error detail types

6167

# in the package `google.rpc` which can be used for common error conditions.

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

6172

# is not necessarily the actual wire format. When the `Status` message is

6173

# exposed in different client libraries and different wire protocols, it can be

6174

# mapped differently. For example, it will likely be mapped to some exceptions

6175

# 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

6180

# environments, either with or without APIs, to provide a

6181

# consistent developer experience across different environments.

6182

#

6183

# Example uses of this error model include:

6184

#

6185

# - Partial errors. If a service needs to return partial errors to the client,

6186

# it may embed the `Status` in the normal response to indicate the partial

6187

# errors.

6188

#

6189

# - Workflow errors. A typical workflow has multiple steps. Each step may

6190

# have a `Status` message for error reporting purpose.

6191

#

6192

# - Batch operations. If a client uses batch request and batch response, the

6193

# `Status` message should be used directly inside batch response, one for

6194

# each error sub-response.

6195

#

6196

# - Asynchronous operations. If an API call embeds asynchronous operation

6197

# results in its response, the status of those operations should be

6198

# represented directly using the `Status` message.

6199

#

6200

# - Logging. If some API errors are stored in logs, the message `Status` could

6201

# be used directly after any stripping needed for security/privacy reasons.

6202

"message": "A String", # A developer-facing error message, which should be in English. Any

6203

# user-facing error message should be localized and sent in the

6204

# google.rpc.Status.details field, or localized by the client.

6205

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

6206

"details": [ # A list of messages that carry the error details. There will be a

6207

# common set of message types for APIs to use.

6208

{

6209

"a_key": "", # Properties of the object. Contains field @type with type URL.

6210

},

6211

],

6212

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame^]

6213

"done": True or False, # If the value is `false`, it means the operation is still in progress.

6214

# If true, the operation is completed, and either `error` or `response` is

6215

# available.

6216

"response": { # The normal response of the operation in case of success. If the original

6217

# method returns no data on success, such as `Delete`, the response is

6218

# `google.protobuf.Empty`. If the original method is standard

6219

# `Get`/`Create`/`Update`, the response should be the resource. For other

6220

# methods, the response should have the type `XxxResponse`, where `Xxx`

6221

# is the original method name. For example, if the original method name

6222

# is `TakeSnapshot()`, the inferred response type is

6223

# `TakeSnapshotResponse`.

6224

"a_key": "", # Properties of the object. Contains field @type with type URL.

6225

},

6226

"name": "A String", # The server-assigned name, which is only unique within the same service that

6227

# originally returns it. If you use the default HTTP mapping, the

6228

# `name` should have the format of `operations/some/unique/name`.

Jon Wayne Parrott