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

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

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

[diff] [blame]

120

# backend:

121

# rules:

Sai Cheemalapati

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

[diff] [blame]

122

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

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

[diff] [blame]

123

# address: calendar.example.com

124

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

125

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

126

# monitoring, etc.

127

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

128

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

129

},

130

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

131

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

132

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

133

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

134

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

135

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

136

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

137

#

138

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

139

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

140

# by the API.

141

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

142

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

143

# The maximum length of this value is 256 characters.

144

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

145

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

146

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

147

{ # A description of a label.

148

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

149

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

150

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

151

},

152

],

153

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

154

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

155

# without any article or other determiners. For example,

156

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

157

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

158

# be used in documentation.

159

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

160

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

161

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

162

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

163

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

164

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

165

},

166

],

167

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

168

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

169

#

170

# - name: library.googleapis.com/activity_history

171

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

172

# display_name: Activity

173

# labels:

174

# - key: /customer_id

175

# description: Identifier of a library customer

176

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

177

# Runtime requests that contain labels not specified here are

178

# considered invalid.

179

{ # A description of a label.

180

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

181

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

182

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

183

},

184

],

185

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

186

# the user interface and should be concise.

187

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

188

# the documentation and can contain details.

189

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

190

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

191

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

192

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

193

},

194

],

Sai Cheemalapati

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

[diff] [blame]

195

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

Jon Wayne Parrott

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

[diff] [blame]

196

#

197

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

198

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

199

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

200

# change the names of the system parameters.

201

"rules": [ # Define system parameters.

202

#

203

# The parameters defined here will override the default parameters

204

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

205

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

206

# and names is implementation-dependent.

207

#

208

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

216

# - name: alt

217

# http_header: Response-Content-Type

218

#

219

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

224

# parameters:

225

# - name: api_key

226

# http_header: Api-Key1

227

# - name: api_key

228

# http_header: Api-Key2

229

#

230

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

231

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

232

# methods.

233

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

234

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

235

# names are used the behavior is implementation-dependent.

236

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

237

# parameter-dependent.

238

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

239

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

240

# is implementation-dependent.

241

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

242

# sensitive.

243

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

244

# and etc. It is case sensitive.

245

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

# insensitive.

},

],

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

250

# methods in all APIs.

251

#

252

# Refer to selector for syntax details.

},

],

},

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

257

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

258

#

259

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

260

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

261

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

262

#

263

# Refer to selector for syntax details.

264

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

265

# default depends on the deployment context.

266

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

267

},

268

],

269

},

Sai Cheemalapati

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

[diff] [blame]

270

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

Jon Wayne Parrott

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

[diff] [blame]

271

#

272

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

273

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

274

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

275

# to both producer and consumer projects, whereas the

276

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

277

# consumer project.

278

#

279

# monitored_resources:

280

# - type: library.googleapis.com/branch

281

# labels:

282

# - key: /city

283

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

284

# - key: /name

285

# description: The name of the branch.

286

# metrics:

287

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

292

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

297

# monitoring:

298

# producer_destinations:

299

# - monitored_resource: library.googleapis.com/branch

300

# metrics:

301

# - library.googleapis.com/book/returned_count

302

# consumer_destinations:

303

# - monitored_resource: library.googleapis.com/branch

304

# metrics:

305

# - library.googleapis.com/book/returned_count

306

# - library.googleapis.com/book/overdue_count

307

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

308

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

309

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

310

# one producer destination.

311

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

312

# or the consumer project).

313

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

314

# Service.monitored_resources section.

315

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

316

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

"A String",

],

},

],

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

322

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

323

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

324

# one consumer destination.

325

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

326

# or the consumer project).

327

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

328

# Service.monitored_resources section.

329

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

330

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

"A String",

],

},

],

},

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

337

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

338

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

339

# generate one instead.

340

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

341

#

342

# Example for an API targeted for external use:

343

#

344

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

350

#

351

# - selector: google.calendar.Delegate

352

# oauth:

353

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

354

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

355

#

356

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

357

{ # Authentication rules for the service.

358

#

359

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

360

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

361

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

362

# request.

363

#

364

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

365

# ignored.

366

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

367

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

368

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

369

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

370

#

371

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

372

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

373

#

374

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

375

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

376

# the OAuth scope across all of those APIs.

377

#

378

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

379

# management about how developers will use them in practice.

380

#

381

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

382

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

383

# due to the backend requiring additional scopes or permissions.

384

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

385

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

#

# Example:

#

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

390

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

391

},

392

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

393

{ # User-defined authentication requirements, including support for

394

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

395

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

#

# Example:

#

# provider_id: bookstore_auth

400

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

401

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

402

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

403

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

404

# "https://Service_name/API_name"

405

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

406

# LibraryService API will only accept JWTs with the following audience

407

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

412

# bookstore_web.apps.googleusercontent.com

413

},

414

],

Jon Wayne Parrott

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

[diff] [blame]

415

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

416

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

417

#

418

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

419

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

420

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

421

# project.

Jon Wayne Parrott

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

[diff] [blame]

422

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

423

#

424

# Refer to selector for syntax details.

425

},

426

],

427

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

428

{ # Configuration for an anthentication provider, including support for

429

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

430

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

431

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

432

# Optional if the key set document:

433

# - can be retrieved from

434

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

435

# of the issuer.

436

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

437

#

438

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

439

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

440

# `AuthRequirement.provider_id`.

441

#

442

# Example: "bookstore_auth".

443

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

444

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

445

# Usually a URL or an email address.

446

#

447

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

448

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

},

],

},

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

453

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

454

#

455

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

456

{ # Usage configuration rules for the service.

457

#

458

# NOTE: Under development.

459

#

460

#

461

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

462

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

463

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

464

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

465

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

466

# allow/disallow unregistered calls.

467

#

468

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

474

#

475

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

#

# usage:

# rules:

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

480

# allow_unregistered_calls: true

481

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

482

# methods in all APIs.

483

#

484

# Refer to selector for syntax details.

485

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

486

},

487

],

488

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

489

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

490

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

"A String",

],

},

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

495

# influence interpretation of the configuration, for example, to

496

# determine defaults. This is documented together with applicable

497

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

498

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

499

# Members of this project can manage the service configuration,

500

# manage consumption of the service, etc.

501

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

502

# HttpRule, each specifying the mapping of an RPC method

503

# to one or more HTTP REST API methods.

504

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

505

#

506

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

507

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

508

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

509

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

510

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

511

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

512

# for details.

513

#

514

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

515

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

516

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

517

# operation on a resource collection of messages:

518

#

519

# ```proto

520

# service Messaging {

521

# rpc GetMessage(GetMessageRequest) returns (Message) {

522

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

523

# }

524

# }

525

# message GetMessageRequest {

526

# message SubMessage {

527

# string subfield = 1;

528

# }

529

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

530

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

531

# }

532

# message Message {

533

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

538

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

543

#

544

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

545

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

546

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

547

#

548

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

549

# pattern automatically become (optional) HTTP query

550

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

551

#

552

# ```proto

553

# message GetMessageRequest {

554

# message SubMessage {

555

# string subfield = 1;

556

# }

557

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

558

# int64 revision = 2; // becomes a parameter

559

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

# }

# ```

#

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

568

#

569

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

570

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

571

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

572

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

573

#

574

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

575

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

576

# message resource collection:

577

#

578

# ```proto

579

# service Messaging {

580

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

581

# option (google.api.http) = {

582

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

588

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

589

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

# }

# ```

#

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

594

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

595

# protos JSON encoding:

#

# HTTP | RPC

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

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

600

#

601

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

602

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

603

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

608

# rpc UpdateMessage(Message) returns (Message) {

609

# option (google.api.http) = {

610

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

626

#

627

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

628

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

629

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

630

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

631

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

632

#

633

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

634

# the `additional_bindings` option. Example:

635

#

636

# ```proto

637

# service Messaging {

638

# rpc GetMessage(GetMessageRequest) returns (Message) {

639

# option (google.api.http) = {

640

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

641

# additional_bindings {

642

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

# }

# };

# }

# }

# message GetMessageRequest {

648

# string message_id = 1;

649

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

659

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

660

#

661

# # Rules for HTTP mapping

662

#

663

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

664

# to the request message are as follows:

665

#

666

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

667

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

668

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

669

# request) can be classified into three types:

670

# (a) Matched in the URL template.

671

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

672

# else everything under the body field)

673

# (c) All other fields.

674

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

675

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

676

#

677

# The syntax of the path template is as follows:

678

#

679

# Template = "/" Segments [ Verb ] ;

680

# Segments = Segment { "/" Segment } ;

681

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

682

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

683

# FieldPath = IDENT { "." IDENT } ;

684

# Verb = ":" LITERAL ;

685

#

686

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

687

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

688

# Expansion.

689

#

690

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

691

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

692

# Expansion.

693

#

694

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

695

#

696

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

697

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

698

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

699

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

700

#

701

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

702

# repeated fields or map fields.

703

#

704

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

705

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

706

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

707

# content to Web (HTML) clients.

708

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

709

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

710

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

711

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

712

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

713

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

714

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

715

# configuration.

716

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

717

# configuration.

718

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

719

},

720

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

721

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

722

# the nesting may only be one level deep).

723

# Object with schema name: HttpRule

724

],

725

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

726

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

727

# configuration.

728

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

729

# configuration.

730

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

731

},

732

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

733

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

734

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

735

},

736

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

737

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

738

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

739

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

740

# at the top-level of response message type.

741

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

742

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

743

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

744

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

745

#

746

# Refer to selector for syntax details.

747

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

},

],

},

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

752

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

753

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

754

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

755

# which cannot be resolved against the associated IDL files.

756

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

757

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

758

{ # Method represents a method of an api.

759

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

760

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

761

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

762

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

763

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

764

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

765

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

766

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

767

# enumeration, etc.

768

"name": "A String", # The option's name. For example, `"java_package"`.

769

"value": { # The option's value. For example, `"com.google.protobuf"`.

770

"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

777

# message.

778

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

779

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

780

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

781

},

782

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

783

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

784

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

785

# and options are inherited as follows:

786

#

787

# - If after comment and whitespace stripping, the documentation

788

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

789

# from the original method.

790

#

791

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

792

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

793

# inherited.

794

#

795

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

796

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

797

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

798

#

799

# Example of a simple mixin:

800

#

801

# package google.acl.v1;

802

# service AccessControl {

803

# // Get the underlying ACL object.

804

# rpc GetAcl(GetAclRequest) returns (Acl) {

805

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

# }

# }

#

# package google.storage.v2;

810

# service Storage {

811

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

812

#

813

# // Get a data record.

814

# rpc GetData(GetDataRequest) returns (Data) {

815

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

# }

# }

#

# Example of a mixin configuration:

820

#

821

# apis:

822

# - name: google.storage.v2.Storage

823

# mixins:

824

# - name: google.acl.v1.AccessControl

825

#

826

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

827

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

828

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

829

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

830

# documentation and annotations as follows:

831

#

832

# service Storage {

833

# // Get the underlying ACL object.

834

# rpc GetAcl(GetAclRequest) returns (Acl) {

835

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

# }

# ...

# }

#

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

841

#

842

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

843

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

844

#

845

# apis:

846

# - name: google.storage.v2.Storage

847

# mixins:

848

# - name: google.acl.v1.AccessControl

849

# root: acls

850

#

851

# This implies the following inherited HTTP annotation:

852

#

853

# service Storage {

854

# // Get the underlying ACL object.

855

# rpc GetAcl(GetAclRequest) returns (Acl) {

856

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

# }

# ...

# }

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

861

# are rooted.

862

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

863

},

864

],

865

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

866

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

867

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

868

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

869

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

870

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

871

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

872

# provided here.

873

#

874

# The versioning schema uses [semantic

875

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

876

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

877

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

878

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

879

# chosen based on the product plan.

880

#

881

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

882

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

883

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

884

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

885

# experimental, none-GA apis.

886

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

887

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

888

# enumeration, etc.

889

"name": "A String", # The option's name. For example, `"java_package"`.

890

"value": { # The option's value. For example, `"com.google.protobuf"`.

891

"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

896

# followed by the api's simple name.

897

},

898

],

899

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

900

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

908

# - google.foo.v1.AnotherError

909

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

910

#

911

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

912

{ # A custom error rule.

913

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

914

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

915

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

916

#

917

# Refer to selector for syntax details.

918

},

919

],

920

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

925

# elements. Restrictions are specified using visibility labels

926

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

927

#

928

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

929

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

930

# elements, plus any unrestricted elements.

931

#

932

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

933

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

940

# restriction: TRUSTED_TESTER

941

# - selector: google.calendar.Calendar.Delegate

942

# restriction: GOOGLE_INTERNAL

943

#

944

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

945

# EnhancedSearch and Delegate.

946

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

947

#

948

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

949

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

950

# element.

Sai Cheemalapati

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

[diff] [blame]

951

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

952

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

Jon Wayne Parrott

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

[diff] [blame]

953

#

954

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

955

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

962

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

963

#

964

# Removing GOOGLE_INTERNAL from this restriction will break clients that

965

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

966

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

967

#

968

# Refer to selector for syntax details.

},

],

},

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

973

{ # Defines a metric type and its schema.

974

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

975

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

976

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

977

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

978

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

Jon Wayne Parrott

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

[diff] [blame]

979

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

980

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

Jon Wayne Parrott

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

[diff] [blame]

981

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

982

# metric type. For example, the

983

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

984

# has a label, `loadbalanced`, that specifies whether the traffic was

985

# received through a load balanced IP address.

986

{ # A description of a label.

987

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

988

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

989

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

990

},

991

],

992

"type": "A String", # The metric type including a DNS name prefix, for example

993

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

994

# should use a natural hierarchical grouping such as the following:

995

#

996

# compute.googleapis.com/instance/cpu/utilization

997

# compute.googleapis.com/instance/disk/read_ops_count

998

# compute.googleapis.com/instance/network/received_bytes_count

999

#

1000

# Note that if the metric type changes, the monitoring data will be

1001

# discontinued, and anything depends on it will break, such as monitoring

1002

# dashboards, alerting rules and quota limits. Therefore, once a metric has

1003

# been published, its type should be immutable.

1004

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

1005

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

1006

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

1007

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

1008

#

1009

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

1024

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

1025

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

1026

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

1027

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

1028

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

1029

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

1030

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

1031

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

1032

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

1033

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

1034

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

1035

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

1036

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

1037

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

1038

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

1039

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

#

# **Grammar**

#

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

1044

#

1045

# The grammar also includes these connectors:

1046

#

1047

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

1048

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

1049

#

1050

# The grammar for a unit is as follows:

1051

#

1052

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

1053

#

1054

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1064

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

1065

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

1066

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

1067

# containing '{' or '}'.

1068

"name": "A String", # Resource name. The format of the name may vary between different

1069

# implementations. For examples:

1070

#

1071

# projects/{project_id}/metricDescriptors/{type=**}

1072

# metricDescriptors/{type=**}

1073

},

1074

],

1075

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

1076

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

1077

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

1078

# should be listed here by name. Example:

1079

#

1080

# enums:

1081

# - name: google.someapi.v1.SomeEnum

1082

{ # Enum type definition.

1083

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

1084

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

1085

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

1086

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

1087

},

1088

"enumvalue": [ # Enum value definitions.

1089

{ # Enum value definition.

1090

"number": 42, # Enum value number.

1091

"options": [ # Protocol buffer options.

1092

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

1093

# enumeration, etc.

1094

"name": "A String", # The option's name. For example, `"java_package"`.

1095

"value": { # The option's value. For example, `"com.google.protobuf"`.

1096

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

},

},

],

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

1101

},

1102

],

1103

"options": [ # Protocol buffer options.

1104

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

1105

# enumeration, etc.

1106

"name": "A String", # The option's name. For example, `"java_package"`.

1107

"value": { # The option's value. For example, `"com.google.protobuf"`.

1108

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

},

},

],

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

1113

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

1114

},

1115

],

1116

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

1117

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

1118

# automatically included. Messages which are not referenced but

1119

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

1120

# should be listed here by name. Example:

1121

#

1122

# types:

1123

# - name: google.protobuf.Int32

1124

{ # A protocol buffer message type.

1125

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

1126

"A String",

1127

],

1128

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

1129

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

1130

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

1131

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

1132

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

1133

},

1134

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

1135

"fields": [ # The list of fields.

1136

{ # A single field of a message type.

1137

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

1138

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

1139

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

1140

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

1141

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

1142

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

1143

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

1144

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

1145

"number": 42, # The field number.

1146

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

1147

"options": [ # The protocol buffer options.

1148

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

1149

# enumeration, etc.

1150

"name": "A String", # The option's name. For example, `"java_package"`.

1151

"value": { # The option's value. For example, `"com.google.protobuf"`.

1152

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

},

},

],

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

1157

},

1158

],

1159

"options": [ # The protocol buffer options.

1160

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

1161

# enumeration, etc.

1162

"name": "A String", # The option's name. For example, `"java_package"`.

1163

"value": { # The option's value. For example, `"com.google.protobuf"`.

1164

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1170

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

Jon Wayne Parrott

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

[diff] [blame]

1171

#

1172

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

1173

# producer and consumer projects. In the example,

1174

# the `library.googleapis.com/activity_history` log is

1175

# sent to both the producer and consumer projects, whereas

1176

# the `library.googleapis.com/purchase_history` log is only sent to the

1177

# producer project:

1178

#

1179

# monitored_resources:

1180

# - type: library.googleapis.com/branch

1181

# labels:

1182

# - key: /city

1183

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

1184

# - key: /name

1185

# description: The name of the branch.

1186

# logs:

1187

# - name: library.googleapis.com/activity_history

1188

# labels:

1189

# - key: /customer_id

1190

# - name: library.googleapis.com/purchase_history

1191

# logging:

1192

# producer_destinations:

1193

# - monitored_resource: library.googleapis.com/branch

1194

# logs:

1195

# - library.googleapis.com/activity_history

1196

# - library.googleapis.com/purchase_history

1197

# consumer_destinations:

1198

# - monitored_resource: library.googleapis.com/branch

1199

# logs:

1200

# - library.googleapis.com/activity_history

1201

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

1202

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

1203

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

1204

# one producer destination.

1205

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

1206

# or the consumer project).

1207

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

1208

# Service.monitored_resources section.

1209

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

1210

# be defined in the Service.logs section.

"A String",

],

},

],

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

1216

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

1217

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

1218

# one consumer destination.

1219

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

1220

# or the consumer project).

1221

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

1222

# Service.monitored_resources section.

1223

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

1224

# be defined in the Service.logs section.

"A String",

],

},

],

},

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

1231

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

1232

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

1233

#

1234

# Example:

1235

# <pre><code>documentation:

1236

# summary: >

1237

# The Google Calendar API gives access

1238

# to most calendar features.

1239

# pages:

1240

# - name: Overview

1241

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

1242

# - name: Tutorial

1243

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

1244

# subpages;

1245

# - name: Java

1246

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

1247

# rules:

1248

# - selector: google.calendar.Calendar.Get

1249

# description: >

1250

# ...

1251

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1256

# standard markdown features, definition lists, tables and fenced

1257

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

1258

# interpreted relative to the section nesting of the context where

1259

# a documentation fragment is embedded.

1260

#

1261

# Documentation from the IDL is merged with documentation defined

1262

# via the config at normalization time, where documentation provided

1263

# by config rules overrides IDL provided.

1264

#

1265

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

1266

# in documentation text.

1267

#

1268

# In order to reference a proto element, the following

1269

# notation can be used:

1270

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

1271

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

1272

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

1273

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

1274

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

1275

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

1276

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

1277

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

1278

# A few directives are available in documentation. Note that

1279

# directives must appear on a single line to be properly

1280

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

1281

# an external source:

1282

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

1283

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

1284

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

1285

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

1286

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

1287

# The directive `suppress_warning` does not directly affect documentation

1288

# and is documented together with service config validation.

1289

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

1290

#

1291

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

1292

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

1293

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

1294

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

1295

# element is marked as `deprecated`.

1296

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

1297

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

1298

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

1299

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

1300

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

# is used.

},

],

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

1305

# <pre><code>documentation:

1306

# summary: ...

1307

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

1308

# </code></pre>

1309

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

1310

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1315

# </code></pre>

1316

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

1317

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

1318

# plain text.

1319

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

1320

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

1321

# nested documentation set structure.

1322

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

1323

# to include content from a Markdown file.

1324

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

1325

# honored in the generated docset.

1326

# Object with schema name: Page

1327

],

1328

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

1329

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

1330

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

1331

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

1332

# documentation. For example:

1333

# <pre><code>pages:

1334

# - name: Tutorial

1335

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

1336

# subpages:

1337

# - name: Java

1338

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

1339

# </code></pre>

1340

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

# `Java`.

},

],

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

1345

},

1346

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

1347

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

1348

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

1349

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

1350

# to define system APIs in ESF.

1351

{ # A protocol buffer message type.

1352

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

1353

"A String",

1354

],

1355

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

1356

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

1357

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

1358

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

1359

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

1360

},

1361

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

1362

"fields": [ # The list of fields.

1363

{ # A single field of a message type.

1364

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

1365

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

1366

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

1367

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

1368

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

1369

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

1370

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

1371

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

1372

"number": 42, # The field number.

1373

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

1374

"options": [ # The protocol buffer options.

1375

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

1376

# enumeration, etc.

1377

"name": "A String", # The option's name. For example, `"java_package"`.

1378

"value": { # The option's value. For example, `"com.google.protobuf"`.

1379

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

},

},

],

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

1384

},

1385

],

1386

"options": [ # The protocol buffer options.

1387

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

1388

# enumeration, etc.

1389

"name": "A String", # The option's name. For example, `"java_package"`.

1390

"value": { # The option's value. For example, `"com.google.protobuf"`.

1391

"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

1406

# - google.rpc.context.OriginContext

1407

#

1408

# The above specifies that all methods in the API request

1409

# `google.rpc.context.ProjectContext` and

1410

# `google.rpc.context.OriginContext`.

1411

#

1412

# Available context types are defined in package

1413

# `google.rpc.context`.

1414

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

1415

#

1416

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

1417

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

1418

# element.

1419

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

1420

"A String",

1421

],

1422

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

1423

"A String",

1424

],

1425

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

1426

#

1427

# Refer to selector for syntax details.

1428

},

1429

],

1430

},

Sai Cheemalapati

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

[diff] [blame]

1431

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

1432

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

1433

# defined APIs.

1434

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

1435

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

1436

# same service configuration, such as quota configuration and monitoring

1437

# configuration.

1438

#

1439

# Example service configuration:

1440

#

1441

# name: library-example.googleapis.com

1442

# endpoints:

1443

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

1444

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

1445

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

1446

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

1447

# # allowed to proceed.

1448

# - name: library-example.googleapis.com

1449

# apis: google.example.library.v1.Library

1450

# allow_cors: true

1451

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

1452

# # API be served from endpoint address

1453

# # google.example.library-example.v1.LibraryManager.

1454

# - name: library-manager.googleapis.com

1455

# apis: google.example.library.v1.LibraryManager

1456

# # BNS address for a borg job. Can specify a task by appending

1457

# # "/taskId" (e.g. "/0") to the job spec.

1458

#

1459

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

1465

# },

1466

# "host": "MY_PROJECT_ID.appspot.com",

1467

# "x-google-endpoints": [{

1468

# "name": "MY_PROJECT_ID.appspot.com",

1469

# "allow_cors": "true"

1470

# }]

1471

# }

1472

"allowCors": True or False, # Allowing

1473

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

1474

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

1475

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

1476

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

1477

# allowed to proceed.

1478

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

1479

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

1480

# alias.

1481

#

1482

# Additional names that this endpoint will be hosted on.

1483

"A String",

1484

],

1485

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

1486

"A String",

1487

],

1488

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

1489

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

"A String",

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1494

}

1495

1496

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1503

Sai Cheemalapati

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

[diff] [blame]

1504

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

1505

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

1506

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

1507

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

1508

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

1513

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

1514

# name: calendar.googleapis.com

1515

# title: Google Calendar API

1516

# apis:

Sai Cheemalapati

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

[diff] [blame]

1517

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame]

1518

# backend:

1519

# rules:

Sai Cheemalapati

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

[diff] [blame]

1520

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

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

[diff] [blame]

1521

# address: calendar.example.com

1522

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

1523

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

1524

# monitoring, etc.

1525

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

1526

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

1527

},

1528

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

1529

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

1530

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

1531

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

1532

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

1533

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

1534

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

1535

#

1536

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

1537

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

1538

# by the API.

1539

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

1540

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

1541

# The maximum length of this value is 256 characters.

1542

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

1543

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

1544

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

1545

{ # A description of a label.

1546

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

1547

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

1548

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

1549

},

1550

],

1551

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

1552

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

1553

# without any article or other determiners. For example,

1554

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

1555

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

1556

# be used in documentation.

1557

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

1558

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

1559

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

1560

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

1561

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

1562

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

1563

},

1564

],

1565

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

1566

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

1567

#

1568

# - name: library.googleapis.com/activity_history

1569

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

1570

# display_name: Activity

1571

# labels:

1572

# - key: /customer_id

1573

# description: Identifier of a library customer

1574

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

1575

# Runtime requests that contain labels not specified here are

1576

# considered invalid.

1577

{ # A description of a label.

1578

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

1579

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

1580

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

1581

},

1582

],

1583

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

1584

# the user interface and should be concise.

1585

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

1586

# the documentation and can contain details.

1587

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

1588

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

1589

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

1590

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

1591

},

1592

],

Sai Cheemalapati

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

[diff] [blame]

1593

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

Jon Wayne Parrott

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

[diff] [blame]

1594

#

1595

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

1596

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

1597

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

1598

# change the names of the system parameters.

1599

"rules": [ # Define system parameters.

1600

#

1601

# The parameters defined here will override the default parameters

1602

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

1603

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

1604

# and names is implementation-dependent.

1605

#

1606

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1614

# - name: alt

1615

# http_header: Response-Content-Type

1616

#

1617

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1622

# parameters:

1623

# - name: api_key

1624

# http_header: Api-Key1

1625

# - name: api_key

1626

# http_header: Api-Key2

1627

#

1628

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

1629

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

1630

# methods.

1631

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

1632

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

1633

# names are used the behavior is implementation-dependent.

1634

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

1635

# parameter-dependent.

1636

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

1637

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

1638

# is implementation-dependent.

1639

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

1640

# sensitive.

1641

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

1642

# and etc. It is case sensitive.

1643

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

# insensitive.

},

],

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

1648

# methods in all APIs.

1649

#

1650

# Refer to selector for syntax details.

},

],

},

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

1655

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

1656

#

1657

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

1658

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

1659

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

1660

#

1661

# Refer to selector for syntax details.

1662

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

1663

# default depends on the deployment context.

1664

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

1665

},

1666

],

1667

},

Sai Cheemalapati

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

[diff] [blame]

1668

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

Jon Wayne Parrott

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

[diff] [blame]

1669

#

1670

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

1671

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

1672

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

1673

# to both producer and consumer projects, whereas the

1674

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

1675

# consumer project.

1676

#

1677

# monitored_resources:

1678

# - type: library.googleapis.com/branch

1679

# labels:

1680

# - key: /city

1681

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

1682

# - key: /name

1683

# description: The name of the branch.

1684

# metrics:

1685

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1690

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1695

# monitoring:

1696

# producer_destinations:

1697

# - monitored_resource: library.googleapis.com/branch

1698

# metrics:

1699

# - library.googleapis.com/book/returned_count

1700

# consumer_destinations:

1701

# - monitored_resource: library.googleapis.com/branch

1702

# metrics:

1703

# - library.googleapis.com/book/returned_count

1704

# - library.googleapis.com/book/overdue_count

1705

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

1706

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

1707

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

1708

# one producer destination.

1709

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

1710

# or the consumer project).

1711

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

1712

# Service.monitored_resources section.

1713

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

1714

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

"A String",

],

},

],

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

1720

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

1721

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

1722

# one consumer destination.

1723

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

1724

# or the consumer project).

1725

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

1726

# Service.monitored_resources section.

1727

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

1728

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

"A String",

],

},

],

},

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

1735

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

1736

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

1737

# generate one instead.

1738

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

1739

#

1740

# Example for an API targeted for external use:

1741

#

1742

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

1748

#

1749

# - selector: google.calendar.Delegate

1750

# oauth:

1751

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

1752

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

1753

#

1754

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

1755

{ # Authentication rules for the service.

1756

#

1757

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

1758

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

1759

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

1760

# request.

1761

#

1762

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

1763

# ignored.

1764

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

1765

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

1766

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

1767

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

1768

#

1769

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

1770

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

1771

#

1772

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

1773

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

1774

# the OAuth scope across all of those APIs.

1775

#

1776

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

1777

# management about how developers will use them in practice.

1778

#

1779

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

1780

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

1781

# due to the backend requiring additional scopes or permissions.

1782

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

1783

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

#

# Example:

#

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

1788

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

1789

},

1790

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

1791

{ # User-defined authentication requirements, including support for

1792

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

1793

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

#

# Example:

#

# provider_id: bookstore_auth

1798

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

1799

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

1800

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

1801

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

1802

# "https://Service_name/API_name"

1803

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

1804

# LibraryService API will only accept JWTs with the following audience

1805

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1810

# bookstore_web.apps.googleusercontent.com

1811

},

1812

],

Jon Wayne Parrott

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

[diff] [blame]

1813

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

1814

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

1815

#

1816

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

1817

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

1818

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

1819

# project.

Jon Wayne Parrott

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

[diff] [blame]

1820

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

1821

#

1822

# Refer to selector for syntax details.

1823

},

1824

],

1825

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

1826

{ # Configuration for an anthentication provider, including support for

1827

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

1828

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

1829

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

1830

# Optional if the key set document:

1831

# - can be retrieved from

1832

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

1833

# of the issuer.

1834

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

1835

#

1836

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

1837

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

1838

# `AuthRequirement.provider_id`.

1839

#

1840

# Example: "bookstore_auth".

1841

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

1842

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

1843

# Usually a URL or an email address.

1844

#

1845

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

1846

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

},

],

},

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

1851

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

1852

#

1853

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

1854

{ # Usage configuration rules for the service.

1855

#

1856

# NOTE: Under development.

1857

#

1858

#

1859

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

1860

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

1861

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

1862

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

1863

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

1864

# allow/disallow unregistered calls.

1865

#

1866

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1872

#

1873

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

#

# usage:

# rules:

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

1878

# allow_unregistered_calls: true

1879

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

1880

# methods in all APIs.

1881

#

1882

# Refer to selector for syntax details.

1883

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

1884

},

1885

],

1886

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

1887

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

1888

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

"A String",

],

},

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

1893

# influence interpretation of the configuration, for example, to

1894

# determine defaults. This is documented together with applicable

1895

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

1896

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

1897

# Members of this project can manage the service configuration,

1898

# manage consumption of the service, etc.

1899

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

1900

# HttpRule, each specifying the mapping of an RPC method

1901

# to one or more HTTP REST API methods.

1902

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

1903

#

1904

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

1905

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

1906

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

1907

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

1908

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

1909

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

1910

# for details.

1911

#

1912

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

1913

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

1914

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

1915

# operation on a resource collection of messages:

1916

#

1917

# ```proto

1918

# service Messaging {

1919

# rpc GetMessage(GetMessageRequest) returns (Message) {

1920

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

1921

# }

1922

# }

1923

# message GetMessageRequest {

1924

# message SubMessage {

1925

# string subfield = 1;

1926

# }

1927

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

1928

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

1929

# }

1930

# message Message {

1931

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

1936

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

1941

#

1942

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

1943

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

1944

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

1945

#

1946

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

1947

# pattern automatically become (optional) HTTP query

1948

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

1949

#

1950

# ```proto

1951

# message GetMessageRequest {

1952

# message SubMessage {

1953

# string subfield = 1;

1954

# }

1955

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

1956

# int64 revision = 2; // becomes a parameter

1957

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

# }

# ```

#

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

1966

#

1967

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

1968

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

1969

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

1970

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

1971

#

1972

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

1973

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

1974

# message resource collection:

1975

#

1976

# ```proto

1977

# service Messaging {

1978

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

1979

# option (google.api.http) = {

1980

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

1986

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

1987

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

# }

# ```

#

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

1992

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

1993

# protos JSON encoding:

#

# HTTP | RPC

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

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

1998

#

1999

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

2000

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

2001

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

2006

# rpc UpdateMessage(Message) returns (Message) {

2007

# option (google.api.http) = {

2008

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

2024

#

2025

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

2026

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

2027

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

2028

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

2029

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

2030

#

2031

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

2032

# the `additional_bindings` option. Example:

2033

#

2034

# ```proto

2035

# service Messaging {

2036

# rpc GetMessage(GetMessageRequest) returns (Message) {

2037

# option (google.api.http) = {

2038

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

2039

# additional_bindings {

2040

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

# }

# };

# }

# }

# message GetMessageRequest {

2046

# string message_id = 1;

2047

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

2057

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

2058

#

2059

# # Rules for HTTP mapping

2060

#

2061

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

2062

# to the request message are as follows:

2063

#

2064

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

2065

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

2066

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

2067

# request) can be classified into three types:

2068

# (a) Matched in the URL template.

2069

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

2070

# else everything under the body field)

2071

# (c) All other fields.

2072

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

2073

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

2074

#

2075

# The syntax of the path template is as follows:

2076

#

2077

# Template = "/" Segments [ Verb ] ;

2078

# Segments = Segment { "/" Segment } ;

2079

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

2080

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

2081

# FieldPath = IDENT { "." IDENT } ;

2082

# Verb = ":" LITERAL ;

2083

#

2084

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

2085

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

2086

# Expansion.

2087

#

2088

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

2089

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

2090

# Expansion.

2091

#

2092

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

2093

#

2094

# The syntax `Variable` matches the entire path as specified by its template;

2095

# this nested template must not contain further variables. If a variable

2096

# matches a single path segment, its template may be omitted, e.g. `{var}`

2097

# is equivalent to `{var=*}`.

2098

#

2099

# NOTE: the field paths in variables and in the `body` must not refer to

2100

# repeated fields or map fields.

2101

#

2102

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2103

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2104

# a given URL path rule. The wild-card rule is useful for services that provide

2105

# content to Web (HTML) clients.

2106

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2107

# `*` for mapping all fields not captured by the path pattern to the HTTP

2108

# body. NOTE: the referred field must not be a repeated field and must be

2109

# present at the top-level of response message type.

2110

"get": "A String", # Used for listing and getting information about resources.

2111

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2112

# [][google.bytestream.RestByteStream] as an API to your

2113

# configuration.

2114

# [][google.bytestream.RestByteStream] as an API to your

2115

# configuration.

2116

"enabled": True or False, # Whether download is enabled.

2117

},

2118

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2119

# not contain an `additional_bindings` field themselves (that is,

2120

# the nesting may only be one level deep).

2121

# Object with schema name: HttpRule

2122

],

2123

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2124

# [][google.bytestream.RestByteStream] as an API to your

2125

# configuration.

2126

# [][google.bytestream.RestByteStream] as an API to your

2127

# configuration.

2128

"enabled": True or False, # Whether upload is enabled.

2129

},

2130

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2131

"path": "A String", # The path matched by this custom verb.

2132

"kind": "A String", # The name of this custom HTTP verb.

2133

},

2134

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2135

# response. Other response fields are ignored. This field is optional. When

2136

# not set, the response message will be used as HTTP body of response.

2137

# NOTE: the referred field must be not a repeated field and must be present

2138

# at the top-level of response message type.

2139

"put": "A String", # Used for updating a resource.

2140

"patch": "A String", # Used for updating a resource.

2141

"post": "A String", # Used for creating a resource.

2142

"selector": "A String", # Selects methods to which this rule applies.

2143

#

2144

# Refer to selector for syntax details.

2145

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2150

# of the google.protobuf.Api needs to be provided by the configuration

2151

# author, as the remaining fields will be derived from the IDL during the

2152

# normalization process. It is an error to specify an API interface here

2153

# which cannot be resolved against the associated IDL files.

2154

{ # Api is a light-weight descriptor for a protocol buffer service.

2155

"methods": [ # The methods of this api, in unspecified order.

2156

{ # Method represents a method of an api.

2157

"name": "A String", # The simple name of this method.

2158

"requestStreaming": True or False, # If true, the request is streamed.

2159

"responseTypeUrl": "A String", # The URL of the output message type.

2160

"requestTypeUrl": "A String", # A URL of the input message type.

2161

"responseStreaming": True or False, # If true, the response is streamed.

2162

"syntax": "A String", # The source syntax of this method.

2163

"options": [ # Any metadata attached to the method.

2164

{ # A protocol buffer option, which can be attached to a message, field,

2165

# enumeration, etc.

2166

"name": "A String", # The option's name. For example, `"java_package"`.

2167

"value": { # The option's value. For example, `"com.google.protobuf"`.

2168

"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

2175

# message.

2176

# protobuf element, like the file in which it is defined.

2177

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2178

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2179

},

2180

"mixins": [ # Included APIs. See Mixin.

2181

{ # Declares an API to be included in this API. The including API must

2182

# redeclare all the methods from the included API, but documentation

2183

# and options are inherited as follows:

2184

#

2185

# - If after comment and whitespace stripping, the documentation

2186

# string of the redeclared method is empty, it will be inherited

2187

# from the original method.

2188

#

2189

# - Each annotation belonging to the service config (http,

2190

# visibility) which is not set in the redeclared method will be

2191

# inherited.

2192

#

2193

# - If an http annotation is inherited, the path pattern will be

2194

# modified as follows. Any version prefix will be replaced by the

2195

# version of the including API plus the root path if specified.

2196

#

2197

# Example of a simple mixin:

2198

#

2199

# package google.acl.v1;

2200

# service AccessControl {

2201

# // Get the underlying ACL object.

2202

# rpc GetAcl(GetAclRequest) returns (Acl) {

2203

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2208

# service Storage {

2209

# // rpc GetAcl(GetAclRequest) returns (Acl);

2210

#

2211

# // Get a data record.

2212

# rpc GetData(GetDataRequest) returns (Data) {

2213

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2218

#

2219

# apis:

2220

# - name: google.storage.v2.Storage

2221

# mixins:

2222

# - name: google.acl.v1.AccessControl

2223

#

2224

# The mixin construct implies that all methods in `AccessControl` are

2225

# also declared with same name and request/response types in

2226

# `Storage`. A documentation generator or annotation processor will

2227

# see the effective `Storage.GetAcl` method after inherting

2228

# documentation and annotations as follows:

2229

#

2230

# service Storage {

2231

# // Get the underlying ACL object.

2232

# rpc GetAcl(GetAclRequest) returns (Acl) {

2233

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2239

#

2240

# If the `root` field in the mixin is specified, it should be a

2241

# relative path under which inherited HTTP paths are placed. Example:

2242

#

2243

# apis:

2244

# - name: google.storage.v2.Storage

2245

# mixins:

2246

# - name: google.acl.v1.AccessControl

2247

# root: acls

2248

#

2249

# This implies the following inherited HTTP annotation:

2250

#

2251

# service Storage {

2252

# // Get the underlying ACL object.

2253

# rpc GetAcl(GetAclRequest) returns (Acl) {

2254

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2259

# are rooted.

2260

"name": "A String", # The fully qualified name of the API which is included.

2261

},

2262

],

2263

"syntax": "A String", # The source syntax of the service.

2264

"version": "A String", # A version string for this api. If specified, must have the form

2265

# `major-version.minor-version`, as in `1.10`. If the minor version

2266

# is omitted, it defaults to zero. If the entire version field is

2267

# empty, the major version is derived from the package name, as

2268

# outlined below. If the field is not empty, the version in the

2269

# package name will be verified to be consistent with what is

2270

# provided here.

2271

#

2272

# The versioning schema uses [semantic

2273

# versioning](http://semver.org) where the major version number

2274

# indicates a breaking change and the minor version an additive,

2275

# non-breaking change. Both version numbers are signals to users

2276

# what to expect from different versions, and should be carefully

2277

# chosen based on the product plan.

2278

#

2279

# The major version is also reflected in the package name of the

2280

# API, which must end in `v<major-version>`, as in

2281

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2282

# be omitted. Zero major versions must only be used for

2283

# experimental, none-GA apis.

2284

"options": [ # Any metadata attached to the API.

2285

{ # A protocol buffer option, which can be attached to a message, field,

2286

# enumeration, etc.

2287

"name": "A String", # The option's name. For example, `"java_package"`.

2288

"value": { # The option's value. For example, `"com.google.protobuf"`.

2289

"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

2294

# followed by the api's simple name.

2295

},

2296

],

2297

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2298

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2306

# - google.foo.v1.AnotherError

2307

"rules": [ # The list of custom error rules that apply to individual API messages.

2308

#

2309

# **NOTE:** All service configuration rules follow "last one wins" order.

2310

{ # A custom error rule.

2311

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2312

# objects of this type will be filtered when they appear in error payload.

2313

"selector": "A String", # Selects messages to which this rule applies.

2314

#

2315

# Refer to selector for syntax details.

2316

},

2317

],

2318

"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.

2323

# elements. Restrictions are specified using visibility labels

2324

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2325

#

2326

# Users and projects can have access to more than one visibility label. The

2327

# effective visibility for multiple labels is the union of each label's

2328

# elements, plus any unrestricted elements.

2329

#

2330

# If an element and its parents have no restrictions, visibility is

2331

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2338

# restriction: TRUSTED_TESTER

2339

# - selector: google.calendar.Calendar.Delegate

2340

# restriction: GOOGLE_INTERNAL

2341

#

2342

# Here, all methods are publicly visible except for the restricted methods

2343

# EnhancedSearch and Delegate.

2344

"rules": [ # A list of visibility rules that apply to individual API elements.

2345

#

2346

# **NOTE:** All service configuration rules follow "last one wins" order.

2347

{ # A visibility rule provides visibility configuration for an individual API

2348

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2349

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

2350

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2351

#

2352

# If a rule has multiple labels, removing one of the labels but not all of

2353

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2360

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2361

#

2362

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2363

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2364

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2365

#

2366

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

2371

{ # Defines a metric type and its schema.

2372

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2373

# Use sentence case without an ending period, for example "Request count".

2374

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2375

"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]

2376

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2377

"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]

2378

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2379

"labels": [ # The set of labels that can be used to describe a specific instance of this

2380

# metric type. For example, the

2381

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

2382

# has a label, `loadbalanced`, that specifies whether the traffic was

2383

# received through a load balanced IP address.

2384

{ # A description of a label.

2385

"valueType": "A String", # The type of data that can be assigned to the label.

2386

"description": "A String", # A human-readable description for the label.

2387

"key": "A String", # The label key.

2388

},

2389

],

2390

"type": "A String", # The metric type including a DNS name prefix, for example

2391

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

2392

# should use a natural hierarchical grouping such as the following:

2393

#

2394

# compute.googleapis.com/instance/cpu/utilization

2395

# compute.googleapis.com/instance/disk/read_ops_count

2396

# compute.googleapis.com/instance/network/received_bytes_count

2397

#

2398

# Note that if the metric type changes, the monitoring data will be

2399

# discontinued, and anything depends on it will break, such as monitoring

2400

# dashboards, alerting rules and quota limits. Therefore, once a metric has

2401

# been published, its type should be immutable.

2402

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2403

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2404

# supported units are a subset of [The Unified Code for Units of

2405

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2406

#

2407

# **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)

2422

# * `P` peta (10**15)

2423

# * `E` exa (10**18)

2424

# * `Z` zetta (10**21)

2425

# * `Y` yotta (10**24)

2426

# * `m` milli (10**-3)

2427

# * `u` micro (10**-6)

2428

# * `n` nano (10**-9)

2429

# * `p` pico (10**-12)

2430

# * `f` femto (10**-15)

2431

# * `a` atto (10**-18)

2432

# * `z` zepto (10**-21)

2433

# * `y` yocto (10**-24)

2434

# * `Ki` kibi (2**10)

2435

# * `Mi` mebi (2**20)

2436

# * `Gi` gibi (2**30)

2437

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2442

#

2443

# The grammar also includes these connectors:

2444

#

2445

# * `/` division (as an infix operator, e.g. `1/s`).

2446

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2447

#

2448

# The grammar for a unit is as follows:

2449

#

2450

# Expression = Component { "." Component } { "/" Component } ;

2451

#

2452

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2462

# equivalent to `1` if it is used alone. For examples,

2463

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2464

# * `NAME` is a sequence of non-blank printable ASCII characters not

2465

# containing '{' or '}'.

2466

"name": "A String", # Resource name. The format of the name may vary between different

2467

# implementations. For examples:

2468

#

2469

# projects/{project_id}/metricDescriptors/{type=**}

2470

# metricDescriptors/{type=**}

2471

},

2472

],

2473

"enums": [ # A list of all enum types included in this API service. Enums

2474

# referenced directly or indirectly by the `apis` are automatically

2475

# included. Enums which are not referenced but shall be included

2476

# should be listed here by name. Example:

2477

#

2478

# enums:

2479

# - name: google.someapi.v1.SomeEnum

2480

{ # Enum type definition.

2481

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2482

# protobuf element, like the file in which it is defined.

2483

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2484

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2485

},

2486

"enumvalue": [ # Enum value definitions.

2487

{ # Enum value definition.

2488

"number": 42, # Enum value number.

2489

"options": [ # Protocol buffer options.

2490

{ # A protocol buffer option, which can be attached to a message, field,

2491

# enumeration, etc.

2492

"name": "A String", # The option's name. For example, `"java_package"`.

2493

"value": { # The option's value. For example, `"com.google.protobuf"`.

2494

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

2499

},

2500

],

2501

"options": [ # Protocol buffer options.

2502

{ # A protocol buffer option, which can be attached to a message, field,

2503

# enumeration, etc.

2504

"name": "A String", # The option's name. For example, `"java_package"`.

2505

"value": { # The option's value. For example, `"com.google.protobuf"`.

2506

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2511

"syntax": "A String", # The source syntax.

2512

},

2513

],

2514

"types": [ # A list of all proto message types included in this API service.

2515

# Types referenced directly or indirectly by the `apis` are

2516

# automatically included. Messages which are not referenced but

2517

# shall be included, such as types used by the `google.protobuf.Any` type,

2518

# should be listed here by name. Example:

2519

#

2520

# types:

2521

# - name: google.protobuf.Int32

2522

{ # A protocol buffer message type.

2523

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2524

"A String",

2525

],

2526

"name": "A String", # The fully qualified message name.

2527

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2528

# protobuf element, like the file in which it is defined.

2529

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2530

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2531

},

2532

"syntax": "A String", # The source syntax.

2533

"fields": [ # The list of fields.

2534

{ # A single field of a message type.

2535

"kind": "A String", # The field type.

2536

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2537

# types. The first type has index 1; zero means the type is not in the list.

2538

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2539

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2540

"name": "A String", # The field name.

2541

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2542

"jsonName": "A String", # The field JSON name.

2543

"number": 42, # The field number.

2544

"cardinality": "A String", # The field cardinality.

2545

"options": [ # The protocol buffer options.

2546

{ # A protocol buffer option, which can be attached to a message, field,

2547

# enumeration, etc.

2548

"name": "A String", # The option's name. For example, `"java_package"`.

2549

"value": { # The option's value. For example, `"com.google.protobuf"`.

2550

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2555

},

2556

],

2557

"options": [ # The protocol buffer options.

2558

{ # A protocol buffer option, which can be attached to a message, field,

2559

# enumeration, etc.

2560

"name": "A String", # The option's name. For example, `"java_package"`.

2561

"value": { # The option's value. For example, `"com.google.protobuf"`.

2562

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2568

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2569

#

2570

# The following example shows how to configure logs to be sent to the

2571

# producer and consumer projects. In the example,

2572

# the `library.googleapis.com/activity_history` log is

2573

# sent to both the producer and consumer projects, whereas

2574

# the `library.googleapis.com/purchase_history` log is only sent to the

2575

# producer project:

2576

#

2577

# monitored_resources:

2578

# - type: library.googleapis.com/branch

2579

# labels:

2580

# - key: /city

2581

# description: The city where the library branch is located in.

2582

# - key: /name

2583

# description: The name of the branch.

2584

# logs:

2585

# - name: library.googleapis.com/activity_history

2586

# labels:

2587

# - key: /customer_id

2588

# - name: library.googleapis.com/purchase_history

2589

# logging:

2590

# producer_destinations:

2591

# - monitored_resource: library.googleapis.com/branch

2592

# logs:

2593

# - library.googleapis.com/activity_history

2594

# - library.googleapis.com/purchase_history

2595

# consumer_destinations:

2596

# - monitored_resource: library.googleapis.com/branch

2597

# logs:

2598

# - library.googleapis.com/activity_history

2599

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2600

# There can be multiple producer destinations, each one must have a

2601

# different monitored resource type. A log can be used in at most

2602

# one producer destination.

2603

{ # Configuration of a specific logging destination (the producer project

2604

# or the consumer project).

2605

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2606

# Service.monitored_resources section.

2607

"logs": [ # Names of the logs to be sent to this destination. Each name must

2608

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

2614

# There can be multiple consumer destinations, each one must have a

2615

# different monitored resource type. A log can be used in at most

2616

# one consumer destination.

2617

{ # Configuration of a specific logging destination (the producer project

2618

# or the consumer project).

2619

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

2620

# Service.monitored_resources section.

2621

"logs": [ # Names of the logs to be sent to this destination. Each name must

2622

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

2629

# e.g. `calendar.googleapis.com`.

2630

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2631

#

2632

# Example:

2633

# <pre><code>documentation:

2634

# summary: >

2635

# The Google Calendar API gives access

2636

# to most calendar features.

2637

# pages:

2638

# - name: Overview

2639

# content: (== include google/foo/overview.md ==)

2640

# - name: Tutorial

2641

# content: (== include google/foo/tutorial.md ==)

2642

# subpages;

2643

# - name: Java

2644

# content: (== include google/foo/tutorial_java.md ==)

2645

# rules:

2646

# - selector: google.calendar.Calendar.Get

2647

# description: >

2648

# ...

2649

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2654

# standard markdown features, definition lists, tables and fenced

2655

# code blocks are supported. Section headers can be provided and are

2656

# interpreted relative to the section nesting of the context where

2657

# a documentation fragment is embedded.

2658

#

2659

# Documentation from the IDL is merged with documentation defined

2660

# via the config at normalization time, where documentation provided

2661

# by config rules overrides IDL provided.

2662

#

2663

# A number of constructs specific to the API platform are supported

2664

# in documentation text.

2665

#

2666

# In order to reference a proto element, the following

2667

# notation can be used:

2668

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2669

# To override the display text used for the link, this can be used:

2670

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2671

# Text can be excluded from doc using the following notation:

2672

# <pre><code>(-- internal comment --)</code></pre>

2673

# Comments can be made conditional using a visibility label. The below

2674

# text will be only rendered if the `BETA` label is available:

2675

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2676

# A few directives are available in documentation. Note that

2677

# directives must appear on a single line to be properly

2678

# identified. The `include` directive includes a markdown file from

2679

# an external source:

2680

# <pre><code>(== include path/to/file ==)</code></pre>

2681

# The `resource_for` directive marks a message to be the resource of

2682

# a collection in REST view. If it is not specified, tools attempt

2683

# to infer the resource from the operations in a collection:

2684

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2685

# The directive `suppress_warning` does not directly affect documentation

2686

# and is documented together with service config validation.

2687

"rules": [ # A list of documentation rules that apply to individual API elements.

2688

#

2689

# **NOTE:** All service configuration rules follow "last one wins" order.

2690

{ # A documentation rule provides information about individual API elements.

2691

"description": "A String", # Description of the selected API(s).

2692

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2693

# element is marked as `deprecated`.

2694

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2695

# qualified name of the element which may end in "*", indicating a wildcard.

2696

# Wildcards are only allowed at the end and for a whole component of the

2697

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2698

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

2703

# <pre><code>documentation:

2704

# summary: ...

2705

# overview: (== include overview.md ==)

2706

# </code></pre>

2707

# This is a shortcut for the following declaration (using pages style):

2708

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2713

# </code></pre>

2714

# Note: you cannot specify both `overview` field and `pages` field.

2715

"summary": "A String", # A short summary of what the service does. Can only be provided by

2716

# plain text.

2717

"pages": [ # The top level pages for the documentation set.

2718

{ # Represents a documentation page. A page can contain subpages to represent

2719

# nested documentation set structure.

2720

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2721

# to include content from a Markdown file.

2722

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2723

# honored in the generated docset.

2724

# Object with schema name: Page

2725

],

2726

"name": "A String", # The name of the page. It will be used as an identity of the page to

2727

# generate URI of the page, text of the link to this page in navigation,

2728

# etc. The full page name (start from the root page name to this page

2729

# concatenated with `.`) can be used as reference to the page in your

2730

# documentation. For example:

2731

# <pre><code>pages:

2732

# - name: Tutorial

2733

# content: (== include tutorial.md ==)

2734

# subpages:

2735

# - name: Java

2736

# content: (== include tutorial_java.md ==)

2737

# </code></pre>

2738

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

2743

},

2744

"systemTypes": [ # A list of all proto message types included in this API service.

2745

# It serves similar purpose as [google.api.Service.types], except that

2746

# these types are not needed by user-defined APIs. Therefore, they will not

2747

# show up in the generated discovery doc. This field should only be used

2748

# to define system APIs in ESF.

2749

{ # A protocol buffer message type.

2750

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2751

"A String",

2752

],

2753

"name": "A String", # The fully qualified message name.

2754

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2755

# protobuf element, like the file in which it is defined.

2756

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2757

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2758

},

2759

"syntax": "A String", # The source syntax.

2760

"fields": [ # The list of fields.

2761

{ # A single field of a message type.

2762

"kind": "A String", # The field type.

2763

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2764

# types. The first type has index 1; zero means the type is not in the list.

2765

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2766

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2767

"name": "A String", # The field name.

2768

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2769

"jsonName": "A String", # The field JSON name.

2770

"number": 42, # The field number.

2771

"cardinality": "A String", # The field cardinality.

2772

"options": [ # The protocol buffer options.

2773

{ # A protocol buffer option, which can be attached to a message, field,

2774

# enumeration, etc.

2775

"name": "A String", # The option's name. For example, `"java_package"`.

2776

"value": { # The option's value. For example, `"com.google.protobuf"`.

2777

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2782

},

2783

],

2784

"options": [ # The protocol buffer options.

2785

{ # A protocol buffer option, which can be attached to a message, field,

2786

# enumeration, etc.

2787

"name": "A String", # The option's name. For example, `"java_package"`.

2788

"value": { # The option's value. For example, `"com.google.protobuf"`.

2789

"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

2804

# - google.rpc.context.OriginContext

2805

#

2806

# The above specifies that all methods in the API request

2807

# `google.rpc.context.ProjectContext` and

2808

# `google.rpc.context.OriginContext`.

2809

#

2810

# Available context types are defined in package

2811

# `google.rpc.context`.

2812

"rules": [ # A list of RPC context rules that apply to individual API methods.

2813

#

2814

# **NOTE:** All service configuration rules follow "last one wins" order.

2815

{ # A context rule provides information about the context for an individual API

2816

# element.

2817

"provided": [ # A list of full type names of provided contexts.

2818

"A String",

2819

],

2820

"requested": [ # A list of full type names of requested contexts.

2821

"A String",

2822

],

2823

"selector": "A String", # Selects the methods to which this rule applies.

2824

#

2825

# Refer to selector for syntax details.

2826

},

2827

],

2828

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2829

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2830

# with the same name as the service is automatically generated to service all

2831

# defined APIs.

2832

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2833

# A service may expose any number of endpoints, and all endpoints share the

2834

# same service configuration, such as quota configuration and monitoring

2835

# configuration.

2836

#

2837

# Example service configuration:

2838

#

2839

# name: library-example.googleapis.com

2840

# endpoints:

2841

# # Below entry makes 'google.example.library.v1.Library'

2842

# # API be served from endpoint address library-example.googleapis.com.

2843

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2844

# # it to decide whether the subsequent cross-origin request is

2845

# # allowed to proceed.

2846

# - name: library-example.googleapis.com

2847

# apis: google.example.library.v1.Library

2848

# allow_cors: true

2849

# # Below entry makes 'google.example.library.v1.Library'

2850

# # API be served from endpoint address

2851

# # google.example.library-example.v1.LibraryManager.

2852

# - name: library-manager.googleapis.com

2853

# apis: google.example.library.v1.LibraryManager

2854

# # BNS address for a borg job. Can specify a task by appending

2855

# # "/taskId" (e.g. "/0") to the job spec.

2856

#

2857

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

2863

# },

2864

# "host": "MY_PROJECT_ID.appspot.com",

2865

# "x-google-endpoints": [{

2866

# "name": "MY_PROJECT_ID.appspot.com",

2867

# "allow_cors": "true"

2868

# }]

2869

# }

2870

"allowCors": True or False, # Allowing

2871

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2872

# cross-domain traffic, would allow the backends served from this endpoint to

2873

# receive and respond to HTTP OPTIONS requests. The response will be used by

2874

# the browser to determine whether the subsequent cross-origin request is

2875

# allowed to proceed.

2876

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2877

# please specify multiple google.api.Endpoint for each of the intented

2878

# alias.

2879

#

2880

# Additional names that this endpoint will be hosted on.

2881

"A String",

2882

],

2883

"features": [ # The list of features enabled on this endpoint.

2884

"A String",

2885

],

2886

"name": "A String", # The canonical name of this endpoint.

2887

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

}</pre>

</div>

<code class="details" id="get">get(serviceName=None, configId, x__xgafv=None)</code>

2897

<pre>Gets a service configuration (version) for a managed service.

2898

2899

Args:

2900

serviceName: string, The name of the service. See the [overview](/service-management/overview)

2901

for naming requirements. For example: `example.googleapis.com`. (required)

2902

configId: string, A parameter (required)

2903

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2910

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2911

{ # `Service` is the root object of Google service configuration schema. It

2912

# describes basic information about a service, such as the name and the

2913

# title, and delegates other aspects to sub-sections. Each sub-section is

2914

# either a proto message or a repeated proto message that configures a

2915

# 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]

2920

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2921

# name: calendar.googleapis.com

2922

# title: Google Calendar API

2923

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2924

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2925

# backend:

2926

# rules:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2927

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2928

# address: calendar.example.com

2929

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

2930

# service controller handles features like abuse, quota, billing, logging,

2931

# monitoring, etc.

2932

"environment": "A String", # The service control environment to use. If empty, no control plane

2933

# feature (like quota and billing) will be enabled.

2934

},

2935

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

2936

# by the Service.monitoring and Service.logging configurations.

2937

{ # An object that describes the schema of a MonitoredResource object using a

2938

# type name and a set of labels. For example, the monitored resource

2939

# descriptor for Google Compute Engine VM instances has a type of

2940

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

2941

# `"zone"` to identify particular VM instances.

2942

#

2943

# Different APIs can support different monitored resource types. APIs generally

2944

# provide a `list` method that returns the monitored resource descriptors used

2945

# by the API.

2946

"type": "A String", # Required. The monitored resource type. For example, the type

2947

# `"cloudsql_database"` represents databases in Google Cloud SQL.

2948

# The maximum length of this value is 256 characters.

2949

"labels": [ # Required. A set of labels used to describe instances of this monitored

2950

# resource type. For example, an individual Google Cloud SQL database is

2951

# identified by values for the labels `"database_id"` and `"zone"`.

2952

{ # A description of a label.

2953

"valueType": "A String", # The type of data that can be assigned to the label.

2954

"description": "A String", # A human-readable description for the label.

2955

"key": "A String", # The label key.

2956

},

2957

],

2958

"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]

2959

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

2960

# without any article or other determiners. For example,

2961

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2962

"description": "A String", # Optional. A detailed description of the monitored resource type that might

2963

# be used in documentation.

2964

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

2965

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

2966

# {type} is the value of the `type` field in this object and

2967

# {project_id} is a project ID that provides API-specific context for

2968

# accessing the type. APIs that do not use project information can use the

2969

# resource name format `"monitoredResourceDescriptors/{type}"`.

2970

},

2971

],

2972

"logs": [ # Defines the logs used by this service.

2973

{ # A description of a log type. Example in YAML format:

2974

#

2975

# - name: library.googleapis.com/activity_history

2976

# description: The history of borrowing and returning library items.

2977

# display_name: Activity

2978

# labels:

2979

# - key: /customer_id

2980

# description: Identifier of a library customer

2981

"labels": [ # The set of labels that are available to describe a specific log entry.

2982

# Runtime requests that contain labels not specified here are

2983

# considered invalid.

2984

{ # A description of a label.

2985

"valueType": "A String", # The type of data that can be assigned to the label.

2986

"description": "A String", # A human-readable description for the label.

2987

"key": "A String", # The label key.

2988

},

2989

],

2990

"displayName": "A String", # The human-readable name for this log. This information appears on

2991

# the user interface and should be concise.

2992

"description": "A String", # A human-readable description of this log. This information appears in

2993

# the documentation and can contain details.

2994

"name": "A String", # The name of the log. It must be less than 512 characters long and can

2995

# include the following characters: upper- and lower-case alphanumeric

2996

# characters [A-Za-z0-9], and punctuation characters including

2997

# slash, underscore, hyphen, period [/_-.].

2998

},

2999

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3000

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3001

#

3002

# A system parameter is a special kind of parameter defined by the API

3003

# system, not by an individual API. It is typically mapped to an HTTP header

3004

# and/or a URL query parameter. This configuration specifies which methods

3005

# change the names of the system parameters.

3006

"rules": [ # Define system parameters.

3007

#

3008

# The parameters defined here will override the default parameters

3009

# implemented by the system. If this field is missing from the service

3010

# config, default system parameters will be used. Default system parameters

3011

# and names is implementation-dependent.

3012

#

3013

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3021

# - name: alt

3022

# http_header: Response-Content-Type

3023

#

3024

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3029

# parameters:

3030

# - name: api_key

3031

# http_header: Api-Key1

3032

# - name: api_key

3033

# http_header: Api-Key2

3034

#

3035

# **NOTE:** All service configuration rules follow "last one wins" order.

3036

{ # Define a system parameter rule mapping system parameter definitions to

3037

# methods.

3038

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3039

# For a given method call, only one of them should be used. If multiple

3040

# names are used the behavior is implementation-dependent.

3041

# If none of the specified names are present the behavior is

3042

# parameter-dependent.

3043

{ # Define a parameter's name and location. The parameter may be passed as either

3044

# an HTTP header or a URL query parameter, and if both are passed the behavior

3045

# is implementation-dependent.

3046

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3047

# sensitive.

3048

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

3049

# and etc. It is case sensitive.

3050

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3055

# methods in all APIs.

3056

#

3057

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3062

"rules": [ # A list of API backend rules that apply to individual API methods.

3063

#

3064

# **NOTE:** All service configuration rules follow "last one wins" order.

3065

{ # A backend rule provides configuration for an individual API element.

3066

"selector": "A String", # Selects the methods to which this rule applies.

3067

#

3068

# Refer to selector for syntax details.

3069

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

3070

# default depends on the deployment context.

3071

"address": "A String", # The address of the API backend.

3072

},

3073

],

3074

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3075

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3076

#

3077

# The example below shows how to configure monitored resources and metrics

3078

# for monitoring. In the example, a monitored resource and two metrics are

3079

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3080

# to both producer and consumer projects, whereas the

3081

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3082

# consumer project.

3083

#

3084

# monitored_resources:

3085

# - type: library.googleapis.com/branch

3086

# labels:

3087

# - key: /city

3088

# description: The city where the library branch is located in.

3089

# - key: /name

3090

# description: The name of the branch.

3091

# metrics:

3092

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3097

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3102

# monitoring:

3103

# producer_destinations:

3104

# - monitored_resource: library.googleapis.com/branch

3105

# metrics:

3106

# - library.googleapis.com/book/returned_count

3107

# consumer_destinations:

3108

# - monitored_resource: library.googleapis.com/branch

3109

# metrics:

3110

# - library.googleapis.com/book/returned_count

3111

# - library.googleapis.com/book/overdue_count

3112

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3113

# There can be multiple producer destinations, each one must have a

3114

# different monitored resource type. A metric can be used in at most

3115

# one producer destination.

3116

{ # Configuration of a specific monitoring destination (the producer project

3117

# or the consumer project).

3118

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3119

# Service.monitored_resources section.

3120

"metrics": [ # Names of the metrics to report to this monitoring destination.

3121

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3127

# There can be multiple consumer destinations, each one must have a

3128

# different monitored resource type. A metric can be used in at most

3129

# one consumer destination.

3130

{ # Configuration of a specific monitoring destination (the producer project

3131

# or the consumer project).

3132

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3133

# Service.monitored_resources section.

3134

"metrics": [ # Names of the metrics to report to this monitoring destination.

3135

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

3142

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3143

# by the client for tracking purpose. If empty, the server may choose to

3144

# generate one instead.

3145

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3146

#

3147

# Example for an API targeted for external use:

3148

#

3149

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

3155

#

3156

# - selector: google.calendar.Delegate

3157

# oauth:

3158

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

3159

"rules": [ # A list of authentication rules that apply to individual API methods.

3160

#

3161

# **NOTE:** All service configuration rules follow "last one wins" order.

3162

{ # Authentication rules for the service.

3163

#

3164

# By default, if a method has any authentication requirements, every request

3165

# must include a valid credential matching one of the requirements.

3166

# It's an error to include more than one kind of credential in a single

3167

# request.

3168

#

3169

# If a method doesn't have any auth requirements, request credentials will be

3170

# ignored.

3171

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3172

# there are scopes defined for "Read-only access to Google Calendar" and

3173

# "Access to Cloud Platform". Users can consent to a scope for an application,

3174

# giving it permission to access that data on their behalf.

3175

#

3176

# OAuth scope specifications should be fairly coarse grained; a user will need

3177

# to see and understand the text description of what your scope means.

3178

#

3179

# In most cases: use one or at most two OAuth scopes for an entire family of

3180

# products. If your product has multiple APIs, you should probably be sharing

3181

# the OAuth scope across all of those APIs.

3182

#

3183

# When you need finer grained OAuth consent screens: talk with your product

3184

# management about how developers will use them in practice.

3185

#

3186

# Please note that even though each of the canonical scopes is enough for a

3187

# request to be accepted and passed to the backend, a request can still fail

3188

# due to the backend requiring additional scopes or permissions.

3189

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3190

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3195

# https://www.googleapis.com/auth/calendar.read

3196

},

3197

"requirements": [ # Requirements for additional authentication providers.

3198

{ # User-defined authentication requirements, including support for

3199

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3200

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3205

"audiences": "A String", # The list of JWT

3206

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3207

# that are allowed to access. A JWT containing any of these audiences will

3208

# be accepted. When this setting is absent, only JWTs with audience

3209

# "https://Service_name/API_name"

3210

# will be accepted. For example, if no audiences are in the setting,

3211

# LibraryService API will only accept JWTs with the following audience

3212

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3217

# bookstore_web.apps.googleusercontent.com

3218

},

3219

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

3220

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3221

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3222

#

3223

# For requests without credentials, if the service control environment is

3224

# specified, each incoming request **must** be associated with a service

3225

# consumer. This can be done by passing an API key that belongs to a consumer

3226

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3227

"selector": "A String", # Selects the methods to which this rule applies.

3228

#

3229

# Refer to selector for syntax details.

3230

},

3231

],

3232

"providers": [ # Defines a set of authentication providers that a service supports.

3233

{ # Configuration for an anthentication provider, including support for

3234

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3235

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3236

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3237

# Optional if the key set document:

3238

# - can be retrieved from

3239

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3240

# of the issuer.

3241

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3242

#

3243

# Example: https://www.googleapis.com/oauth2/v1/certs

3244

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3245

# `AuthRequirement.provider_id`.

3246

#

3247

# Example: "bookstore_auth".

3248

"issuer": "A String", # Identifies the principal that issued the JWT. See

3249

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3250

# Usually a URL or an email address.

3251

#

3252

# Example: https://securetoken.google.com

3253

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3258

"rules": [ # A list of usage rules that apply to individual API methods.

3259

#

3260

# **NOTE:** All service configuration rules follow "last one wins" order.

3261

{ # Usage configuration rules for the service.

3262

#

3263

# NOTE: Under development.

3264

#

3265

#

3266

# Use this rule to configure unregistered calls for the service. Unregistered

3267

# calls are calls that do not contain consumer project identity.

3268

# (Example: calls that do not contain an API key).

3269

# By default, API methods do not allow unregistered calls, and each method call

3270

# must be identified by a consumer project identity. Use this rule to

3271

# allow/disallow unregistered calls.

3272

#

3273

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3279

#

3280

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3285

# allow_unregistered_calls: true

3286

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3287

# methods in all APIs.

3288

#

3289

# Refer to selector for syntax details.

3290

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3291

},

3292

],

3293

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3294

# service. Each requirement is of the form <service.name>/<requirement-id>;

3295

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3300

# influence interpretation of the configuration, for example, to

3301

# determine defaults. This is documented together with applicable

3302

# options. The current default for the config version itself is `3`.

3303

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3304

# Members of this project can manage the service configuration,

3305

# manage consumption of the service, etc.

3306

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3307

# HttpRule, each specifying the mapping of an RPC method

3308

# to one or more HTTP REST API methods.

3309

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3310

#

3311

# **NOTE:** All service configuration rules follow "last one wins" order.

3312

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3313

# REST APIs. The mapping determines what portions of the request

3314

# message are populated from the path, query parameters, or body of

3315

# the HTTP request. The mapping is typically specified as an

3316

# `google.api.http` annotation, see "google/api/annotations.proto"

3317

# for details.

3318

#

3319

# The mapping consists of a field specifying the path template and

3320

# method kind. The path template can refer to fields in the request

3321

# message, as in the example below which describes a REST GET

3322

# operation on a resource collection of messages:

3323

#

3324

# ```proto

3325

# service Messaging {

3326

# rpc GetMessage(GetMessageRequest) returns (Message) {

3327

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3328

# }

3329

# }

3330

# message GetMessageRequest {

3331

# message SubMessage {

3332

# string subfield = 1;

3333

# }

3334

# string message_id = 1; // mapped to the URL

3335

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3336

# }

3337

# message Message {

3338

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

3343

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3348

#

3349

# In general, not only fields but also field paths can be referenced

3350

# from a path pattern. Fields mapped to the path pattern cannot be

3351

# repeated and must have a primitive (non-message) type.

3352

#

3353

# Any fields in the request message which are not bound by the path

3354

# pattern automatically become (optional) HTTP query

3355

# parameters. Assume the following definition of the request message:

3356

#

3357

# ```proto

3358

# message GetMessageRequest {

3359

# message SubMessage {

3360

# string subfield = 1;

3361

# }

3362

# string message_id = 1; // mapped to the URL

3363

# int64 revision = 2; // becomes a parameter

3364

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# 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"))`

3373

#

3374

# Note that fields which are mapped to HTTP parameters must have a

3375

# primitive type or a repeated primitive type. Message types are not

3376

# allowed. In the case of a repeated type, the parameter can be

3377

# repeated in the URL, as in `...?param=A&param=B`.

3378

#

3379

# For HTTP method kinds which allow a request body, the `body` field

3380

# specifies the mapping. Consider a REST update method on the

3381

# message resource collection:

3382

#

3383

# ```proto

3384

# service Messaging {

3385

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3386

# option (google.api.http) = {

3387

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3393

# string message_id = 1; // mapped to the URL

3394

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

3399

# representation of the JSON in the request body is determined by

3400

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3405

#

3406

# The special name `*` can be used in the body mapping to define that

3407

# every field not bound by the path template should be mapped to the

3408

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

3413

# rpc UpdateMessage(Message) returns (Message) {

3414

# option (google.api.http) = {

3415

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

3431

#

3432

# Note that when using `*` in the body mapping, it is not possible to

3433

# have HTTP parameters, as all fields not bound by the path end in

3434

# the body. This makes this option more rarely used in practice of

3435

# defining REST APIs. The common usage of `*` is in custom methods

3436

# which don't use the URL at all for transferring data.

3437

#

3438

# It is possible to define multiple HTTP methods for one RPC by using

3439

# the `additional_bindings` option. Example:

3440

#

3441

# ```proto

3442

# service Messaging {

3443

# rpc GetMessage(GetMessageRequest) returns (Message) {

3444

# option (google.api.http) = {

3445

# get: "/v1/messages/{message_id}"

3446

# additional_bindings {

3447

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

3453

# string message_id = 1;

3454

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

3464

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

3465

#

3466

# # Rules for HTTP mapping

3467

#

3468

# The rules for mapping HTTP path, query parameters, and body fields

3469

# to the request message are as follows:

3470

#

3471

# 1. The `body` field specifies either `*` or a field path, or is

3472

# omitted. If omitted, it assumes there is no HTTP body.

3473

# 2. Leaf fields (recursive expansion of nested messages in the

3474

# request) can be classified into three types:

3475

# (a) Matched in the URL template.

3476

# (b) Covered by body (if body is `*`, everything except (a) fields;

3477

# else everything under the body field)

3478

# (c) All other fields.

3479

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

3480

# 4. Any body sent with an HTTP request can contain only (b) fields.

3481

#

3482

# The syntax of the path template is as follows:

3483

#

3484

# Template = "/" Segments [ Verb ] ;

3485

# Segments = Segment { "/" Segment } ;

3486

# Segment = "*" | "**" | LITERAL | Variable ;

3487

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3488

# FieldPath = IDENT { "." IDENT } ;

3489

# Verb = ":" LITERAL ;

3490

#

3491

# The syntax `*` matches a single path segment. It follows the semantics of

3492

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3493

# Expansion.

3494

#

3495

# The syntax `**` matches zero or more path segments. It follows the semantics

3496

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

3497

# Expansion.

3498

#

3499

# The syntax `LITERAL` matches literal text in the URL path.

3500

#

3501

# The syntax `Variable` matches the entire path as specified by its template;

3502

# this nested template must not contain further variables. If a variable

3503

# matches a single path segment, its template may be omitted, e.g. `{var}`

3504

# is equivalent to `{var=*}`.

3505

#

3506

# NOTE: the field paths in variables and in the `body` must not refer to

3507

# repeated fields or map fields.

3508

#

3509

# Use CustomHttpPattern to specify any HTTP method that is not included in the

3510

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

3511

# a given URL path rule. The wild-card rule is useful for services that provide

3512

# content to Web (HTML) clients.

3513

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

3514

# `*` for mapping all fields not captured by the path pattern to the HTTP

3515

# body. NOTE: the referred field must not be a repeated field and must be

3516

# present at the top-level of response message type.

3517

"get": "A String", # Used for listing and getting information about resources.

3518

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3519

# [][google.bytestream.RestByteStream] as an API to your

3520

# configuration.

3521

# [][google.bytestream.RestByteStream] as an API to your

3522

# configuration.

3523

"enabled": True or False, # Whether download is enabled.

3524

},

3525

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3526

# not contain an `additional_bindings` field themselves (that is,

3527

# the nesting may only be one level deep).

3528

# Object with schema name: HttpRule

3529

],

3530

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3531

# [][google.bytestream.RestByteStream] as an API to your

3532

# configuration.

3533

# [][google.bytestream.RestByteStream] as an API to your

3534

# configuration.

3535

"enabled": True or False, # Whether upload is enabled.

3536

},

3537

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

3538

"path": "A String", # The path matched by this custom verb.

3539

"kind": "A String", # The name of this custom HTTP verb.

3540

},

3541

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

3542

# response. Other response fields are ignored. This field is optional. When

3543

# not set, the response message will be used as HTTP body of response.

3544

# NOTE: the referred field must be not a repeated field and must be present

3545

# at the top-level of response message type.

3546

"put": "A String", # Used for updating a resource.

3547

"patch": "A String", # Used for updating a resource.

3548

"post": "A String", # Used for creating a resource.

3549

"selector": "A String", # Selects methods to which this rule applies.

3550

#

3551

# Refer to selector for syntax details.

3552

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3557

# of the google.protobuf.Api needs to be provided by the configuration

3558

# author, as the remaining fields will be derived from the IDL during the

3559

# normalization process. It is an error to specify an API interface here

3560

# which cannot be resolved against the associated IDL files.

3561

{ # Api is a light-weight descriptor for a protocol buffer service.

3562

"methods": [ # The methods of this api, in unspecified order.

3563

{ # Method represents a method of an api.

3564

"name": "A String", # The simple name of this method.

3565

"requestStreaming": True or False, # If true, the request is streamed.

3566

"responseTypeUrl": "A String", # The URL of the output message type.

3567

"requestTypeUrl": "A String", # A URL of the input message type.

3568

"responseStreaming": True or False, # If true, the response is streamed.

3569

"syntax": "A String", # The source syntax of this method.

3570

"options": [ # Any metadata attached to the method.

3571

{ # A protocol buffer option, which can be attached to a message, field,

3572

# enumeration, etc.

3573

"name": "A String", # The option's name. For example, `"java_package"`.

3574

"value": { # The option's value. For example, `"com.google.protobuf"`.

3575

"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

3582

# message.

3583

# protobuf element, like the file in which it is defined.

3584

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3585

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3586

},

3587

"mixins": [ # Included APIs. See Mixin.

3588

{ # Declares an API to be included in this API. The including API must

3589

# redeclare all the methods from the included API, but documentation

3590

# and options are inherited as follows:

3591

#

3592

# - If after comment and whitespace stripping, the documentation

3593

# string of the redeclared method is empty, it will be inherited

3594

# from the original method.

3595

#

3596

# - Each annotation belonging to the service config (http,

3597

# visibility) which is not set in the redeclared method will be

3598

# inherited.

3599

#

3600

# - If an http annotation is inherited, the path pattern will be

3601

# modified as follows. Any version prefix will be replaced by the

3602

# version of the including API plus the root path if specified.

3603

#

3604

# Example of a simple mixin:

3605

#

3606

# package google.acl.v1;

3607

# service AccessControl {

3608

# // Get the underlying ACL object.

3609

# rpc GetAcl(GetAclRequest) returns (Acl) {

3610

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3615

# service Storage {

3616

# // rpc GetAcl(GetAclRequest) returns (Acl);

3617

#

3618

# // Get a data record.

3619

# rpc GetData(GetDataRequest) returns (Data) {

3620

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3625

#

3626

# apis:

3627

# - name: google.storage.v2.Storage

3628

# mixins:

3629

# - name: google.acl.v1.AccessControl

3630

#

3631

# The mixin construct implies that all methods in `AccessControl` are

3632

# also declared with same name and request/response types in

3633

# `Storage`. A documentation generator or annotation processor will

3634

# see the effective `Storage.GetAcl` method after inherting

3635

# documentation and annotations as follows:

3636

#

3637

# service Storage {

3638

# // Get the underlying ACL object.

3639

# rpc GetAcl(GetAclRequest) returns (Acl) {

3640

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3646

#

3647

# If the `root` field in the mixin is specified, it should be a

3648

# relative path under which inherited HTTP paths are placed. Example:

3649

#

3650

# apis:

3651

# - name: google.storage.v2.Storage

3652

# mixins:

3653

# - name: google.acl.v1.AccessControl

3654

# root: acls

3655

#

3656

# This implies the following inherited HTTP annotation:

3657

#

3658

# service Storage {

3659

# // Get the underlying ACL object.

3660

# rpc GetAcl(GetAclRequest) returns (Acl) {

3661

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3666

# are rooted.

3667

"name": "A String", # The fully qualified name of the API which is included.

3668

},

3669

],

3670

"syntax": "A String", # The source syntax of the service.

3671

"version": "A String", # A version string for this api. If specified, must have the form

3672

# `major-version.minor-version`, as in `1.10`. If the minor version

3673

# is omitted, it defaults to zero. If the entire version field is

3674

# empty, the major version is derived from the package name, as

3675

# outlined below. If the field is not empty, the version in the

3676

# package name will be verified to be consistent with what is

3677

# provided here.

3678

#

3679

# The versioning schema uses [semantic

3680

# versioning](http://semver.org) where the major version number

3681

# indicates a breaking change and the minor version an additive,

3682

# non-breaking change. Both version numbers are signals to users

3683

# what to expect from different versions, and should be carefully

3684

# chosen based on the product plan.

3685

#

3686

# The major version is also reflected in the package name of the

3687

# API, which must end in `v<major-version>`, as in

3688

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3689

# be omitted. Zero major versions must only be used for

3690

# experimental, none-GA apis.

3691

"options": [ # Any metadata attached to the API.

3692

{ # A protocol buffer option, which can be attached to a message, field,

3693

# enumeration, etc.

3694

"name": "A String", # The option's name. For example, `"java_package"`.

3695

"value": { # The option's value. For example, `"com.google.protobuf"`.

3696

"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

3701

# followed by the api's simple name.

3702

},

3703

],

3704

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3705

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3713

# - google.foo.v1.AnotherError

3714

"rules": [ # The list of custom error rules that apply to individual API messages.

3715

#

3716

# **NOTE:** All service configuration rules follow "last one wins" order.

3717

{ # A custom error rule.

3718

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3719

# objects of this type will be filtered when they appear in error payload.

3720

"selector": "A String", # Selects messages to which this rule applies.

3721

#

3722

# Refer to selector for syntax details.

3723

},

3724

],

3725

"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.

3730

# elements. Restrictions are specified using visibility labels

3731

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3732

#

3733

# Users and projects can have access to more than one visibility label. The

3734

# effective visibility for multiple labels is the union of each label's

3735

# elements, plus any unrestricted elements.

3736

#

3737

# If an element and its parents have no restrictions, visibility is

3738

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3745

# restriction: TRUSTED_TESTER

3746

# - selector: google.calendar.Calendar.Delegate

3747

# restriction: GOOGLE_INTERNAL

3748

#

3749

# Here, all methods are publicly visible except for the restricted methods

3750

# EnhancedSearch and Delegate.

3751

"rules": [ # A list of visibility rules that apply to individual API elements.

3752

#

3753

# **NOTE:** All service configuration rules follow "last one wins" order.

3754

{ # A visibility rule provides visibility configuration for an individual API

3755

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3756

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

3757

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3758

#

3759

# If a rule has multiple labels, removing one of the labels but not all of

3760

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3767

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

3768

#

3769

# Removing GOOGLE_INTERNAL from this restriction will break clients that

3770

# rely on this method and only had access to it through GOOGLE_INTERNAL.

3771

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

3772

#

3773

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

3778

{ # Defines a metric type and its schema.

3779

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3780

# Use sentence case without an ending period, for example "Request count".

3781

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3782

"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]

3783

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3784

"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]

3785

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3786

"labels": [ # The set of labels that can be used to describe a specific instance of this

3787

# metric type. For example, the

3788

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

3789

# has a label, `loadbalanced`, that specifies whether the traffic was

3790

# received through a load balanced IP address.

3791

{ # A description of a label.

3792

"valueType": "A String", # The type of data that can be assigned to the label.

3793

"description": "A String", # A human-readable description for the label.

3794

"key": "A String", # The label key.

3795

},

3796

],

3797

"type": "A String", # The metric type including a DNS name prefix, for example

3798

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

3799

# should use a natural hierarchical grouping such as the following:

3800

#

3801

# compute.googleapis.com/instance/cpu/utilization

3802

# compute.googleapis.com/instance/disk/read_ops_count

3803

# compute.googleapis.com/instance/network/received_bytes_count

3804

#

3805

# Note that if the metric type changes, the monitoring data will be

3806

# discontinued, and anything depends on it will break, such as monitoring

3807

# dashboards, alerting rules and quota limits. Therefore, once a metric has

3808

# been published, its type should be immutable.

3809

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

3810

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

3811

# supported units are a subset of [The Unified Code for Units of

3812

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3813

#

3814

# **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)

3829

# * `P` peta (10**15)

3830

# * `E` exa (10**18)

3831

# * `Z` zetta (10**21)

3832

# * `Y` yotta (10**24)

3833

# * `m` milli (10**-3)

3834

# * `u` micro (10**-6)

3835

# * `n` nano (10**-9)

3836

# * `p` pico (10**-12)

3837

# * `f` femto (10**-15)

3838

# * `a` atto (10**-18)

3839

# * `z` zepto (10**-21)

3840

# * `y` yocto (10**-24)

3841

# * `Ki` kibi (2**10)

3842

# * `Mi` mebi (2**20)

3843

# * `Gi` gibi (2**30)

3844

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

3849

#

3850

# The grammar also includes these connectors:

3851

#

3852

# * `/` division (as an infix operator, e.g. `1/s`).

3853

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

3854

#

3855

# The grammar for a unit is as follows:

3856

#

3857

# Expression = Component { "." Component } { "/" Component } ;

3858

#

3859

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

3869

# equivalent to `1` if it is used alone. For examples,

3870

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

3871

# * `NAME` is a sequence of non-blank printable ASCII characters not

3872

# containing '{' or '}'.

3873

"name": "A String", # Resource name. The format of the name may vary between different

3874

# implementations. For examples:

3875

#

3876

# projects/{project_id}/metricDescriptors/{type=**}

3877

# metricDescriptors/{type=**}

3878

},

3879

],

3880

"enums": [ # A list of all enum types included in this API service. Enums

3881

# referenced directly or indirectly by the `apis` are automatically

3882

# included. Enums which are not referenced but shall be included

3883

# should be listed here by name. Example:

3884

#

3885

# enums:

3886

# - name: google.someapi.v1.SomeEnum

3887

{ # Enum type definition.

3888

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3889

# protobuf element, like the file in which it is defined.

3890

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3891

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3892

},

3893

"enumvalue": [ # Enum value definitions.

3894

{ # Enum value definition.

3895

"number": 42, # Enum value number.

3896

"options": [ # Protocol buffer options.

3897

{ # A protocol buffer option, which can be attached to a message, field,

3898

# enumeration, etc.

3899

"name": "A String", # The option's name. For example, `"java_package"`.

3900

"value": { # The option's value. For example, `"com.google.protobuf"`.

3901

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

3906

},

3907

],

3908

"options": [ # Protocol buffer options.

3909

{ # A protocol buffer option, which can be attached to a message, field,

3910

# enumeration, etc.

3911

"name": "A String", # The option's name. For example, `"java_package"`.

3912

"value": { # The option's value. For example, `"com.google.protobuf"`.

3913

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

3918

"syntax": "A String", # The source syntax.

3919

},

3920

],

3921

"types": [ # A list of all proto message types included in this API service.

3922

# Types referenced directly or indirectly by the `apis` are

3923

# automatically included. Messages which are not referenced but

3924

# shall be included, such as types used by the `google.protobuf.Any` type,

3925

# should be listed here by name. Example:

3926

#

3927

# types:

3928

# - name: google.protobuf.Int32

3929

{ # A protocol buffer message type.

3930

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

3931

"A String",

3932

],

3933

"name": "A String", # The fully qualified message name.

3934

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

3935

# protobuf element, like the file in which it is defined.

3936

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3937

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3938

},

3939

"syntax": "A String", # The source syntax.

3940

"fields": [ # The list of fields.

3941

{ # A single field of a message type.

3942

"kind": "A String", # The field type.

3943

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

3944

# types. The first type has index 1; zero means the type is not in the list.

3945

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

3946

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

3947

"name": "A String", # The field name.

3948

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

3949

"jsonName": "A String", # The field JSON name.

3950

"number": 42, # The field number.

3951

"cardinality": "A String", # The field cardinality.

3952

"options": [ # The protocol buffer options.

3953

{ # A protocol buffer option, which can be attached to a message, field,

3954

# enumeration, etc.

3955

"name": "A String", # The option's name. For example, `"java_package"`.

3956

"value": { # The option's value. For example, `"com.google.protobuf"`.

3957

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

3962

},

3963

],

3964

"options": [ # The protocol buffer options.

3965

{ # A protocol buffer option, which can be attached to a message, field,

3966

# enumeration, etc.

3967

"name": "A String", # The option's name. For example, `"java_package"`.

3968

"value": { # The option's value. For example, `"com.google.protobuf"`.

3969

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3975

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3976

#

3977

# The following example shows how to configure logs to be sent to the

3978

# producer and consumer projects. In the example,

3979

# the `library.googleapis.com/activity_history` log is

3980

# sent to both the producer and consumer projects, whereas

3981

# the `library.googleapis.com/purchase_history` log is only sent to the

3982

# producer project:

3983

#

3984

# monitored_resources:

3985

# - type: library.googleapis.com/branch

3986

# labels:

3987

# - key: /city

3988

# description: The city where the library branch is located in.

3989

# - key: /name

3990

# description: The name of the branch.

3991

# logs:

3992

# - name: library.googleapis.com/activity_history

3993

# labels:

3994

# - key: /customer_id

3995

# - name: library.googleapis.com/purchase_history

3996

# logging:

3997

# producer_destinations:

3998

# - monitored_resource: library.googleapis.com/branch

3999

# logs:

4000

# - library.googleapis.com/activity_history

4001

# - library.googleapis.com/purchase_history

4002

# consumer_destinations:

4003

# - monitored_resource: library.googleapis.com/branch

4004

# logs:

4005

# - library.googleapis.com/activity_history

4006

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4007

# There can be multiple producer destinations, each one must have a

4008

# different monitored resource type. A log can be used in at most

4009

# one producer destination.

4010

{ # Configuration of a specific logging destination (the producer project

4011

# or the consumer project).

4012

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4013

# Service.monitored_resources section.

4014

"logs": [ # Names of the logs to be sent to this destination. Each name must

4015

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

4021

# There can be multiple consumer destinations, each one must have a

4022

# different monitored resource type. A log can be used in at most

4023

# one consumer destination.

4024

{ # Configuration of a specific logging destination (the producer project

4025

# or the consumer project).

4026

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4027

# Service.monitored_resources section.

4028

"logs": [ # Names of the logs to be sent to this destination. Each name must

4029

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

4036

# e.g. `calendar.googleapis.com`.

4037

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4038

#

4039

# Example:

4040

# <pre><code>documentation:

4041

# summary: >

4042

# The Google Calendar API gives access

4043

# to most calendar features.

4044

# pages:

4045

# - name: Overview

4046

# content: (== include google/foo/overview.md ==)

4047

# - name: Tutorial

4048

# content: (== include google/foo/tutorial.md ==)

4049

# subpages;

4050

# - name: Java

4051

# content: (== include google/foo/tutorial_java.md ==)

4052

# rules:

4053

# - selector: google.calendar.Calendar.Get

4054

# description: >

4055

# ...

4056

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

4061

# standard markdown features, definition lists, tables and fenced

4062

# code blocks are supported. Section headers can be provided and are

4063

# interpreted relative to the section nesting of the context where

4064

# a documentation fragment is embedded.

4065

#

4066

# Documentation from the IDL is merged with documentation defined

4067

# via the config at normalization time, where documentation provided

4068

# by config rules overrides IDL provided.

4069

#

4070

# A number of constructs specific to the API platform are supported

4071

# in documentation text.

4072

#

4073

# In order to reference a proto element, the following

4074

# notation can be used:

4075

# <pre><code>[fully.qualified.proto.name][]</code></pre>

4076

# To override the display text used for the link, this can be used:

4077

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

4078

# Text can be excluded from doc using the following notation:

4079

# <pre><code>(-- internal comment --)</code></pre>

4080

# Comments can be made conditional using a visibility label. The below

4081

# text will be only rendered if the `BETA` label is available:

4082

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

4083

# A few directives are available in documentation. Note that

4084

# directives must appear on a single line to be properly

4085

# identified. The `include` directive includes a markdown file from

4086

# an external source:

4087

# <pre><code>(== include path/to/file ==)</code></pre>

4088

# The `resource_for` directive marks a message to be the resource of

4089

# a collection in REST view. If it is not specified, tools attempt

4090

# to infer the resource from the operations in a collection:

4091

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

4092

# The directive `suppress_warning` does not directly affect documentation

4093

# and is documented together with service config validation.

4094

"rules": [ # A list of documentation rules that apply to individual API elements.

4095

#

4096

# **NOTE:** All service configuration rules follow "last one wins" order.

4097

{ # A documentation rule provides information about individual API elements.

4098

"description": "A String", # Description of the selected API(s).

4099

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

4100

# element is marked as `deprecated`.

4101

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

4102

# qualified name of the element which may end in "*", indicating a wildcard.

4103

# Wildcards are only allowed at the end and for a whole component of the

4104

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

4105

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

4110

# <pre><code>documentation:

4111

# summary: ...

4112

# overview: (== include overview.md ==)

4113

# </code></pre>

4114

# This is a shortcut for the following declaration (using pages style):

4115

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

4120

# </code></pre>

4121

# Note: you cannot specify both `overview` field and `pages` field.

4122

"summary": "A String", # A short summary of what the service does. Can only be provided by

4123

# plain text.

4124

"pages": [ # The top level pages for the documentation set.

4125

{ # Represents a documentation page. A page can contain subpages to represent

4126

# nested documentation set structure.

4127

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

4128

# to include content from a Markdown file.

4129

"subpages": [ # Subpages of this page. The order of subpages specified here will be

4130

# honored in the generated docset.

4131

# Object with schema name: Page

4132

],

4133

"name": "A String", # The name of the page. It will be used as an identity of the page to

4134

# generate URI of the page, text of the link to this page in navigation,

4135

# etc. The full page name (start from the root page name to this page

4136

# concatenated with `.`) can be used as reference to the page in your

4137

# documentation. For example:

4138

# <pre><code>pages:

4139

# - name: Tutorial

4140

# content: (== include tutorial.md ==)

4141

# subpages:

4142

# - name: Java

4143

# content: (== include tutorial_java.md ==)

4144

# </code></pre>

4145

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

4150

},

4151

"systemTypes": [ # A list of all proto message types included in this API service.

4152

# It serves similar purpose as [google.api.Service.types], except that

4153

# these types are not needed by user-defined APIs. Therefore, they will not

4154

# show up in the generated discovery doc. This field should only be used

4155

# to define system APIs in ESF.

4156

{ # A protocol buffer message type.

4157

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4158

"A String",

4159

],

4160

"name": "A String", # The fully qualified message name.

4161

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4162

# protobuf element, like the file in which it is defined.

4163

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4164

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4165

},

4166

"syntax": "A String", # The source syntax.

4167

"fields": [ # The list of fields.

4168

{ # A single field of a message type.

4169

"kind": "A String", # The field type.

4170

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4171

# types. The first type has index 1; zero means the type is not in the list.

4172

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4173

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4174

"name": "A String", # The field name.

4175

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4176

"jsonName": "A String", # The field JSON name.

4177

"number": 42, # The field number.

4178

"cardinality": "A String", # The field cardinality.

4179

"options": [ # The protocol buffer options.

4180

{ # A protocol buffer option, which can be attached to a message, field,

4181

# enumeration, etc.

4182

"name": "A String", # The option's name. For example, `"java_package"`.

4183

"value": { # The option's value. For example, `"com.google.protobuf"`.

4184

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4189

},

4190

],

4191

"options": [ # The protocol buffer options.

4192

{ # A protocol buffer option, which can be attached to a message, field,

4193

# enumeration, etc.

4194

"name": "A String", # The option's name. For example, `"java_package"`.

4195

"value": { # The option's value. For example, `"com.google.protobuf"`.

4196

"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

4211

# - google.rpc.context.OriginContext

4212

#

4213

# The above specifies that all methods in the API request

4214

# `google.rpc.context.ProjectContext` and

4215

# `google.rpc.context.OriginContext`.

4216

#

4217

# Available context types are defined in package

4218

# `google.rpc.context`.

4219

"rules": [ # A list of RPC context rules that apply to individual API methods.

4220

#

4221

# **NOTE:** All service configuration rules follow "last one wins" order.

4222

{ # A context rule provides information about the context for an individual API

4223

# element.

4224

"provided": [ # A list of full type names of provided contexts.

4225

"A String",

4226

],

4227

"requested": [ # A list of full type names of requested contexts.

4228

"A String",

4229

],

4230

"selector": "A String", # Selects the methods to which this rule applies.

4231

#

4232

# Refer to selector for syntax details.

4233

},

4234

],

4235

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4236

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4237

# with the same name as the service is automatically generated to service all

4238

# defined APIs.

4239

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4240

# A service may expose any number of endpoints, and all endpoints share the

4241

# same service configuration, such as quota configuration and monitoring

4242

# configuration.

4243

#

4244

# Example service configuration:

4245

#

4246

# name: library-example.googleapis.com

4247

# endpoints:

4248

# # Below entry makes 'google.example.library.v1.Library'

4249

# # API be served from endpoint address library-example.googleapis.com.

4250

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4251

# # it to decide whether the subsequent cross-origin request is

4252

# # allowed to proceed.

4253

# - name: library-example.googleapis.com

4254

# apis: google.example.library.v1.Library

4255

# allow_cors: true

4256

# # Below entry makes 'google.example.library.v1.Library'

4257

# # API be served from endpoint address

4258

# # google.example.library-example.v1.LibraryManager.

4259

# - name: library-manager.googleapis.com

4260

# apis: google.example.library.v1.LibraryManager

4261

# # BNS address for a borg job. Can specify a task by appending

4262

# # "/taskId" (e.g. "/0") to the job spec.

4263

#

4264

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

4270

# },

4271

# "host": "MY_PROJECT_ID.appspot.com",

4272

# "x-google-endpoints": [{

4273

# "name": "MY_PROJECT_ID.appspot.com",

4274

# "allow_cors": "true"

4275

# }]

4276

# }

4277

"allowCors": True or False, # Allowing

4278

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4279

# cross-domain traffic, would allow the backends served from this endpoint to

4280

# receive and respond to HTTP OPTIONS requests. The response will be used by

4281

# the browser to determine whether the subsequent cross-origin request is

4282

# allowed to proceed.

4283

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4284

# please specify multiple google.api.Endpoint for each of the intented

4285

# alias.

4286

#

4287

# Additional names that this endpoint will be hosted on.

4288

"A String",

4289

],

4290

"features": [ # The list of features enabled on this endpoint.

4291

"A String",

4292

],

4293

"name": "A String", # The canonical name of this endpoint.

4294

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

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>

4304

<pre>Lists the history of the service configuration for a managed service,

4305

from the newest to the oldest.

4306

4307

Args:

4308

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4309

for naming requirements. For example: `example.googleapis.com`. (required)

4310

pageSize: integer, The max number of items to include in the response list.

4311

pageToken: string, The token of the page to retrieve.

4312

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4319

4320

{ # Response message for ListServiceConfigs method.

4321

"nextPageToken": "A String", # The token of the next page of results.

4322

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4323

{ # `Service` is the root object of Google service configuration schema. It

4324

# describes basic information about a service, such as the name and the

4325

# title, and delegates other aspects to sub-sections. Each sub-section is

4326

# either a proto message or a repeated proto message that configures a

4327

# 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]

4332

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4333

# name: calendar.googleapis.com

4334

# title: Google Calendar API

4335

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4336

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4337

# backend:

4338

# rules:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4339

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4340

# address: calendar.example.com

4341

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4342

# service controller handles features like abuse, quota, billing, logging,

4343

# monitoring, etc.

4344

"environment": "A String", # The service control environment to use. If empty, no control plane

4345

# feature (like quota and billing) will be enabled.

4346

},

4347

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4348

# by the Service.monitoring and Service.logging configurations.

4349

{ # An object that describes the schema of a MonitoredResource object using a

4350

# type name and a set of labels. For example, the monitored resource

4351

# descriptor for Google Compute Engine VM instances has a type of

4352

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4353

# `"zone"` to identify particular VM instances.

4354

#

4355

# Different APIs can support different monitored resource types. APIs generally

4356

# provide a `list` method that returns the monitored resource descriptors used

4357

# by the API.

4358

"type": "A String", # Required. The monitored resource type. For example, the type

4359

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4360

# The maximum length of this value is 256 characters.

4361

"labels": [ # Required. A set of labels used to describe instances of this monitored

4362

# resource type. For example, an individual Google Cloud SQL database is

4363

# identified by values for the labels `"database_id"` and `"zone"`.

4364

{ # A description of a label.

4365

"valueType": "A String", # The type of data that can be assigned to the label.

4366

"description": "A String", # A human-readable description for the label.

4367

"key": "A String", # The label key.

4368

},

4369

],

4370

"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]

4371

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

4372

# without any article or other determiners. For example,

4373

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4374

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4375

# be used in documentation.

4376

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4377

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4378

# {type} is the value of the `type` field in this object and

4379

# {project_id} is a project ID that provides API-specific context for

4380

# accessing the type. APIs that do not use project information can use the

4381

# resource name format `"monitoredResourceDescriptors/{type}"`.

4382

},

4383

],

4384

"logs": [ # Defines the logs used by this service.

4385

{ # A description of a log type. Example in YAML format:

4386

#

4387

# - name: library.googleapis.com/activity_history

4388

# description: The history of borrowing and returning library items.

4389

# display_name: Activity

4390

# labels:

4391

# - key: /customer_id

4392

# description: Identifier of a library customer

4393

"labels": [ # The set of labels that are available to describe a specific log entry.

4394

# Runtime requests that contain labels not specified here are

4395

# considered invalid.

4396

{ # A description of a label.

4397

"valueType": "A String", # The type of data that can be assigned to the label.

4398

"description": "A String", # A human-readable description for the label.

4399

"key": "A String", # The label key.

4400

},

4401

],

4402

"displayName": "A String", # The human-readable name for this log. This information appears on

4403

# the user interface and should be concise.

4404

"description": "A String", # A human-readable description of this log. This information appears in

4405

# the documentation and can contain details.

4406

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4407

# include the following characters: upper- and lower-case alphanumeric

4408

# characters [A-Za-z0-9], and punctuation characters including

4409

# slash, underscore, hyphen, period [/_-.].

4410

},

4411

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4412

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4413

#

4414

# A system parameter is a special kind of parameter defined by the API

4415

# system, not by an individual API. It is typically mapped to an HTTP header

4416

# and/or a URL query parameter. This configuration specifies which methods

4417

# change the names of the system parameters.

4418

"rules": [ # Define system parameters.

4419

#

4420

# The parameters defined here will override the default parameters

4421

# implemented by the system. If this field is missing from the service

4422

# config, default system parameters will be used. Default system parameters

4423

# and names is implementation-dependent.

4424

#

4425

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4433

# - name: alt

4434

# http_header: Response-Content-Type

4435

#

4436

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4441

# parameters:

4442

# - name: api_key

4443

# http_header: Api-Key1

4444

# - name: api_key

4445

# http_header: Api-Key2

4446

#

4447

# **NOTE:** All service configuration rules follow "last one wins" order.

4448

{ # Define a system parameter rule mapping system parameter definitions to

4449

# methods.

4450

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4451

# For a given method call, only one of them should be used. If multiple

4452

# names are used the behavior is implementation-dependent.

4453

# If none of the specified names are present the behavior is

4454

# parameter-dependent.

4455

{ # Define a parameter's name and location. The parameter may be passed as either

4456

# an HTTP header or a URL query parameter, and if both are passed the behavior

4457

# is implementation-dependent.

4458

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4459

# sensitive.

4460

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

4461

# and etc. It is case sensitive.

4462

"httpHeader": "A String", # Define the HTTP header name to use for the parameter. It is case

# insensitive.

},

],

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4467

# methods in all APIs.

4468

#

4469

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4474

"rules": [ # A list of API backend rules that apply to individual API methods.

4475

#

4476

# **NOTE:** All service configuration rules follow "last one wins" order.

4477

{ # A backend rule provides configuration for an individual API element.

4478

"selector": "A String", # Selects the methods to which this rule applies.

4479

#

4480

# Refer to selector for syntax details.

4481

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4482

# default depends on the deployment context.

4483

"address": "A String", # The address of the API backend.

4484

},

4485

],

4486

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4487

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4488

#

4489

# The example below shows how to configure monitored resources and metrics

4490

# for monitoring. In the example, a monitored resource and two metrics are

4491

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4492

# to both producer and consumer projects, whereas the

4493

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4494

# consumer project.

4495

#

4496

# monitored_resources:

4497

# - type: library.googleapis.com/branch

4498

# labels:

4499

# - key: /city

4500

# description: The city where the library branch is located in.

4501

# - key: /name

4502

# description: The name of the branch.

4503

# metrics:

4504

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4509

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4514

# monitoring:

4515

# producer_destinations:

4516

# - monitored_resource: library.googleapis.com/branch

4517

# metrics:

4518

# - library.googleapis.com/book/returned_count

4519

# consumer_destinations:

4520

# - monitored_resource: library.googleapis.com/branch

4521

# metrics:

4522

# - library.googleapis.com/book/returned_count

4523

# - library.googleapis.com/book/overdue_count

4524

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4525

# There can be multiple producer destinations, each one must have a

4526

# different monitored resource type. A metric can be used in at most

4527

# one producer destination.

4528

{ # Configuration of a specific monitoring destination (the producer project

4529

# or the consumer project).

4530

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4531

# Service.monitored_resources section.

4532

"metrics": [ # Names of the metrics to report to this monitoring destination.

4533

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4539

# There can be multiple consumer destinations, each one must have a

4540

# different monitored resource type. A metric can be used in at most

4541

# one consumer destination.

4542

{ # Configuration of a specific monitoring destination (the producer project

4543

# or the consumer project).

4544

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4545

# Service.monitored_resources section.

4546

"metrics": [ # Names of the metrics to report to this monitoring destination.

4547

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

4554

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4555

# by the client for tracking purpose. If empty, the server may choose to

4556

# generate one instead.

4557

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4558

#

4559

# Example for an API targeted for external use:

4560

#

4561

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

4567

#

4568

# - selector: google.calendar.Delegate

4569

# oauth:

4570

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

4571

"rules": [ # A list of authentication rules that apply to individual API methods.

4572

#

4573

# **NOTE:** All service configuration rules follow "last one wins" order.

4574

{ # Authentication rules for the service.

4575

#

4576

# By default, if a method has any authentication requirements, every request

4577

# must include a valid credential matching one of the requirements.

4578

# It's an error to include more than one kind of credential in a single

4579

# request.

4580

#

4581

# If a method doesn't have any auth requirements, request credentials will be

4582

# ignored.

4583

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4584

# there are scopes defined for "Read-only access to Google Calendar" and

4585

# "Access to Cloud Platform". Users can consent to a scope for an application,

4586

# giving it permission to access that data on their behalf.

4587

#

4588

# OAuth scope specifications should be fairly coarse grained; a user will need

4589

# to see and understand the text description of what your scope means.

4590

#

4591

# In most cases: use one or at most two OAuth scopes for an entire family of

4592

# products. If your product has multiple APIs, you should probably be sharing

4593

# the OAuth scope across all of those APIs.

4594

#

4595

# When you need finer grained OAuth consent screens: talk with your product

4596

# management about how developers will use them in practice.

4597

#

4598

# Please note that even though each of the canonical scopes is enough for a

4599

# request to be accepted and passed to the backend, a request can still fail

4600

# due to the backend requiring additional scopes or permissions.

4601

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4602

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4607

# https://www.googleapis.com/auth/calendar.read

4608

},

4609

"requirements": [ # Requirements for additional authentication providers.

4610

{ # User-defined authentication requirements, including support for

4611

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4612

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

4617

"audiences": "A String", # The list of JWT

4618

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4619

# that are allowed to access. A JWT containing any of these audiences will

4620

# be accepted. When this setting is absent, only JWTs with audience

4621

# "https://Service_name/API_name"

4622

# will be accepted. For example, if no audiences are in the setting,

4623

# LibraryService API will only accept JWTs with the following audience

4624

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4629

# bookstore_web.apps.googleusercontent.com

4630

},

4631

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

4632

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

4633

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

4634

#

4635

# For requests without credentials, if the service control environment is

4636

# specified, each incoming request **must** be associated with a service

4637

# consumer. This can be done by passing an API key that belongs to a consumer

4638

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4639

"selector": "A String", # Selects the methods to which this rule applies.

4640

#

4641

# Refer to selector for syntax details.

4642

},

4643

],

4644

"providers": [ # Defines a set of authentication providers that a service supports.

4645

{ # Configuration for an anthentication provider, including support for

4646

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4647

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4648

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4649

# Optional if the key set document:

4650

# - can be retrieved from

4651

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4652

# of the issuer.

4653

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4654

#

4655

# Example: https://www.googleapis.com/oauth2/v1/certs

4656

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4657

# `AuthRequirement.provider_id`.

4658

#

4659

# Example: "bookstore_auth".

4660

"issuer": "A String", # Identifies the principal that issued the JWT. See

4661

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4662

# Usually a URL or an email address.

4663

#

4664

# Example: https://securetoken.google.com

4665

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4670

"rules": [ # A list of usage rules that apply to individual API methods.

4671

#

4672

# **NOTE:** All service configuration rules follow "last one wins" order.

4673

{ # Usage configuration rules for the service.

4674

#

4675

# NOTE: Under development.

4676

#

4677

#

4678

# Use this rule to configure unregistered calls for the service. Unregistered

4679

# calls are calls that do not contain consumer project identity.

4680

# (Example: calls that do not contain an API key).

4681

# By default, API methods do not allow unregistered calls, and each method call

4682

# must be identified by a consumer project identity. Use this rule to

4683

# allow/disallow unregistered calls.

4684

#

4685

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4691

#

4692

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4697

# allow_unregistered_calls: true

4698

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4699

# methods in all APIs.

4700

#

4701

# Refer to selector for syntax details.

4702

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4703

},

4704

],

4705

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4706

# service. Each requirement is of the form <service.name>/<requirement-id>;

4707

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

4712

# influence interpretation of the configuration, for example, to

4713

# determine defaults. This is documented together with applicable

4714

# options. The current default for the config version itself is `3`.

4715

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

4716

# Members of this project can manage the service configuration,

4717

# manage consumption of the service, etc.

4718

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

4719

# HttpRule, each specifying the mapping of an RPC method

4720

# to one or more HTTP REST API methods.

4721

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4722

#

4723

# **NOTE:** All service configuration rules follow "last one wins" order.

4724

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

4725

# REST APIs. The mapping determines what portions of the request

4726

# message are populated from the path, query parameters, or body of

4727

# the HTTP request. The mapping is typically specified as an

4728

# `google.api.http` annotation, see "google/api/annotations.proto"

4729

# for details.

4730

#

4731

# The mapping consists of a field specifying the path template and

4732

# method kind. The path template can refer to fields in the request

4733

# message, as in the example below which describes a REST GET

4734

# operation on a resource collection of messages:

4735

#

4736

# ```proto

4737

# service Messaging {

4738

# rpc GetMessage(GetMessageRequest) returns (Message) {

4739

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4740

# }

4741

# }

4742

# message GetMessageRequest {

4743

# message SubMessage {

4744

# string subfield = 1;

4745

# }

4746

# string message_id = 1; // mapped to the URL

4747

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4748

# }

4749

# message Message {

4750

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

4755

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4760

#

4761

# In general, not only fields but also field paths can be referenced

4762

# from a path pattern. Fields mapped to the path pattern cannot be

4763

# repeated and must have a primitive (non-message) type.

4764

#

4765

# Any fields in the request message which are not bound by the path

4766

# pattern automatically become (optional) HTTP query

4767

# parameters. Assume the following definition of the request message:

4768

#

4769

# ```proto

4770

# message GetMessageRequest {

4771

# message SubMessage {

4772

# string subfield = 1;

4773

# }

4774

# string message_id = 1; // mapped to the URL

4775

# int64 revision = 2; // becomes a parameter

4776

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

# }

# ```

#

# 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"))`

4785

#

4786

# Note that fields which are mapped to HTTP parameters must have a

4787

# primitive type or a repeated primitive type. Message types are not

4788

# allowed. In the case of a repeated type, the parameter can be

4789

# repeated in the URL, as in `...?param=A&param=B`.

4790

#

4791

# For HTTP method kinds which allow a request body, the `body` field

4792

# specifies the mapping. Consider a REST update method on the

4793

# message resource collection:

4794

#

4795

# ```proto

4796

# service Messaging {

4797

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

4798

# option (google.api.http) = {

4799

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

4805

# string message_id = 1; // mapped to the URL

4806

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

4811

# representation of the JSON in the request body is determined by

4812

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

4817

#

4818

# The special name `*` can be used in the body mapping to define that

4819

# every field not bound by the path template should be mapped to the

4820

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

4825

# rpc UpdateMessage(Message) returns (Message) {

4826

# option (google.api.http) = {

4827

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

4843

#

4844

# Note that when using `*` in the body mapping, it is not possible to

4845

# have HTTP parameters, as all fields not bound by the path end in

4846

# the body. This makes this option more rarely used in practice of

4847

# defining REST APIs. The common usage of `*` is in custom methods

4848

# which don't use the URL at all for transferring data.

4849

#

4850

# It is possible to define multiple HTTP methods for one RPC by using

4851

# the `additional_bindings` option. Example:

4852

#

4853

# ```proto

4854

# service Messaging {

4855

# rpc GetMessage(GetMessageRequest) returns (Message) {

4856

# option (google.api.http) = {

4857

# get: "/v1/messages/{message_id}"

4858

# additional_bindings {

4859

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

4865

# string message_id = 1;

4866

# string user_id = 2;

# }

# ```

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

4876

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

4877

#

4878

# # Rules for HTTP mapping

4879

#

4880

# The rules for mapping HTTP path, query parameters, and body fields

4881

# to the request message are as follows:

4882

#

4883

# 1. The `body` field specifies either `*` or a field path, or is

4884

# omitted. If omitted, it assumes there is no HTTP body.

4885

# 2. Leaf fields (recursive expansion of nested messages in the

4886

# request) can be classified into three types:

4887

# (a) Matched in the URL template.

4888

# (b) Covered by body (if body is `*`, everything except (a) fields;

4889

# else everything under the body field)

4890

# (c) All other fields.

4891

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

4892

# 4. Any body sent with an HTTP request can contain only (b) fields.

4893

#

4894

# The syntax of the path template is as follows:

4895

#

4896

# Template = "/" Segments [ Verb ] ;

4897

# Segments = Segment { "/" Segment } ;

4898

# Segment = "*" | "**" | LITERAL | Variable ;

4899

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

4900

# FieldPath = IDENT { "." IDENT } ;

4901

# Verb = ":" LITERAL ;

4902

#

4903

# The syntax `*` matches a single path segment. It follows the semantics of

4904

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

4905

# Expansion.

4906

#

4907

# The syntax `**` matches zero or more path segments. It follows the semantics

4908

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

4909

# Expansion.

4910

#

4911

# The syntax `LITERAL` matches literal text in the URL path.

4912

#

4913

# The syntax `Variable` matches the entire path as specified by its template;

4914

# this nested template must not contain further variables. If a variable

4915

# matches a single path segment, its template may be omitted, e.g. `{var}`

4916

# is equivalent to `{var=*}`.

4917

#

4918

# NOTE: the field paths in variables and in the `body` must not refer to

4919

# repeated fields or map fields.

4920

#

4921

# Use CustomHttpPattern to specify any HTTP method that is not included in the

4922

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

4923

# a given URL path rule. The wild-card rule is useful for services that provide

4924

# content to Web (HTML) clients.

4925

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

4926

# `*` for mapping all fields not captured by the path pattern to the HTTP

4927

# body. NOTE: the referred field must not be a repeated field and must be

4928

# present at the top-level of response message type.

4929

"get": "A String", # Used for listing and getting information about resources.

4930

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4931

# [][google.bytestream.RestByteStream] as an API to your

4932

# configuration.

4933

# [][google.bytestream.RestByteStream] as an API to your

4934

# configuration.

4935

"enabled": True or False, # Whether download is enabled.

4936

},

4937

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

4938

# not contain an `additional_bindings` field themselves (that is,

4939

# the nesting may only be one level deep).

4940

# Object with schema name: HttpRule

4941

],

4942

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

4943

# [][google.bytestream.RestByteStream] as an API to your

4944

# configuration.

4945

# [][google.bytestream.RestByteStream] as an API to your

4946

# configuration.

4947

"enabled": True or False, # Whether upload is enabled.

4948

},

4949

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

4950

"path": "A String", # The path matched by this custom verb.

4951

"kind": "A String", # The name of this custom HTTP verb.

4952

},

4953

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

4954

# response. Other response fields are ignored. This field is optional. When

4955

# not set, the response message will be used as HTTP body of response.

4956

# NOTE: the referred field must be not a repeated field and must be present

4957

# at the top-level of response message type.

4958

"put": "A String", # Used for updating a resource.

4959

"patch": "A String", # Used for updating a resource.

4960

"post": "A String", # Used for creating a resource.

4961

"selector": "A String", # Selects methods to which this rule applies.

4962

#

4963

# Refer to selector for syntax details.

4964

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

4969

# of the google.protobuf.Api needs to be provided by the configuration

4970

# author, as the remaining fields will be derived from the IDL during the

4971

# normalization process. It is an error to specify an API interface here

4972

# which cannot be resolved against the associated IDL files.

4973

{ # Api is a light-weight descriptor for a protocol buffer service.

4974

"methods": [ # The methods of this api, in unspecified order.

4975

{ # Method represents a method of an api.

4976

"name": "A String", # The simple name of this method.

4977

"requestStreaming": True or False, # If true, the request is streamed.

4978

"responseTypeUrl": "A String", # The URL of the output message type.

4979

"requestTypeUrl": "A String", # A URL of the input message type.

4980

"responseStreaming": True or False, # If true, the response is streamed.

4981

"syntax": "A String", # The source syntax of this method.

4982

"options": [ # Any metadata attached to the method.

4983

{ # A protocol buffer option, which can be attached to a message, field,

4984

# enumeration, etc.

4985

"name": "A String", # The option's name. For example, `"java_package"`.

4986

"value": { # The option's value. For example, `"com.google.protobuf"`.

4987

"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

4994

# message.

4995

# protobuf element, like the file in which it is defined.

4996

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4997

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4998

},

4999

"mixins": [ # Included APIs. See Mixin.

5000

{ # Declares an API to be included in this API. The including API must

5001

# redeclare all the methods from the included API, but documentation

5002

# and options are inherited as follows:

5003

#

5004

# - If after comment and whitespace stripping, the documentation

5005

# string of the redeclared method is empty, it will be inherited

5006

# from the original method.

5007

#

5008

# - Each annotation belonging to the service config (http,

5009

# visibility) which is not set in the redeclared method will be

5010

# inherited.

5011

#

5012

# - If an http annotation is inherited, the path pattern will be

5013

# modified as follows. Any version prefix will be replaced by the

5014

# version of the including API plus the root path if specified.

5015

#

5016

# Example of a simple mixin:

5017

#

5018

# package google.acl.v1;

5019

# service AccessControl {

5020

# // Get the underlying ACL object.

5021

# rpc GetAcl(GetAclRequest) returns (Acl) {

5022

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

5027

# service Storage {

5028

# // rpc GetAcl(GetAclRequest) returns (Acl);

5029

#

5030

# // Get a data record.

5031

# rpc GetData(GetDataRequest) returns (Data) {

5032

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

5037

#

5038

# apis:

5039

# - name: google.storage.v2.Storage

5040

# mixins:

5041

# - name: google.acl.v1.AccessControl

5042

#

5043

# The mixin construct implies that all methods in `AccessControl` are

5044

# also declared with same name and request/response types in

5045

# `Storage`. A documentation generator or annotation processor will

5046

# see the effective `Storage.GetAcl` method after inherting

5047

# documentation and annotations as follows:

5048

#

5049

# service Storage {

5050

# // Get the underlying ACL object.

5051

# rpc GetAcl(GetAclRequest) returns (Acl) {

5052

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

5058

#

5059

# If the `root` field in the mixin is specified, it should be a

5060

# relative path under which inherited HTTP paths are placed. Example:

5061

#

5062

# apis:

5063

# - name: google.storage.v2.Storage

5064

# mixins:

5065

# - name: google.acl.v1.AccessControl

5066

# root: acls

5067

#

5068

# This implies the following inherited HTTP annotation:

5069

#

5070

# service Storage {

5071

# // Get the underlying ACL object.

5072

# rpc GetAcl(GetAclRequest) returns (Acl) {

5073

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

5078

# are rooted.

5079

"name": "A String", # The fully qualified name of the API which is included.

5080

},

5081

],

5082

"syntax": "A String", # The source syntax of the service.

5083

"version": "A String", # A version string for this api. If specified, must have the form

5084

# `major-version.minor-version`, as in `1.10`. If the minor version

5085

# is omitted, it defaults to zero. If the entire version field is

5086

# empty, the major version is derived from the package name, as

5087

# outlined below. If the field is not empty, the version in the

5088

# package name will be verified to be consistent with what is

5089

# provided here.

5090

#

5091

# The versioning schema uses [semantic

5092

# versioning](http://semver.org) where the major version number

5093

# indicates a breaking change and the minor version an additive,

5094

# non-breaking change. Both version numbers are signals to users

5095

# what to expect from different versions, and should be carefully

5096

# chosen based on the product plan.

5097

#

5098

# The major version is also reflected in the package name of the

5099

# API, which must end in `v<major-version>`, as in

5100

# `google.feature.v1`. For major versions 0 and 1, the suffix can

5101

# be omitted. Zero major versions must only be used for

5102

# experimental, none-GA apis.

5103

"options": [ # Any metadata attached to the API.

5104

{ # A protocol buffer option, which can be attached to a message, field,

5105

# enumeration, etc.

5106

"name": "A String", # The option's name. For example, `"java_package"`.

5107

"value": { # The option's value. For example, `"com.google.protobuf"`.

5108

"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

5113

# followed by the api's simple name.

5114

},

5115

],

5116

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5117

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5125

# - google.foo.v1.AnotherError

5126

"rules": [ # The list of custom error rules that apply to individual API messages.

5127

#

5128

# **NOTE:** All service configuration rules follow "last one wins" order.

5129

{ # A custom error rule.

5130

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5131

# objects of this type will be filtered when they appear in error payload.

5132

"selector": "A String", # Selects messages to which this rule applies.

5133

#

5134

# Refer to selector for syntax details.

5135

},

5136

],

5137

"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.

5142

# elements. Restrictions are specified using visibility labels

5143

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

5144

#

5145

# Users and projects can have access to more than one visibility label. The

5146

# effective visibility for multiple labels is the union of each label's

5147

# elements, plus any unrestricted elements.

5148

#

5149

# If an element and its parents have no restrictions, visibility is

5150

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5157

# restriction: TRUSTED_TESTER

5158

# - selector: google.calendar.Calendar.Delegate

5159

# restriction: GOOGLE_INTERNAL

5160

#

5161

# Here, all methods are publicly visible except for the restricted methods

5162

# EnhancedSearch and Delegate.

5163

"rules": [ # A list of visibility rules that apply to individual API elements.

5164

#

5165

# **NOTE:** All service configuration rules follow "last one wins" order.

5166

{ # A visibility rule provides visibility configuration for an individual API

5167

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5168

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

5169

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5170

#

5171

# If a rule has multiple labels, removing one of the labels but not all of

5172

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5179

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

5180

#

5181

# Removing GOOGLE_INTERNAL from this restriction will break clients that

5182

# rely on this method and only had access to it through GOOGLE_INTERNAL.

5183

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

5184

#

5185

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

5190

{ # Defines a metric type and its schema.

5191

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5192

# Use sentence case without an ending period, for example "Request count".

5193

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5194

"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]

5195

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5196

"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]

5197

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5198

"labels": [ # The set of labels that can be used to describe a specific instance of this

5199

# metric type. For example, the

5200

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

5201

# has a label, `loadbalanced`, that specifies whether the traffic was

5202

# received through a load balanced IP address.

5203

{ # A description of a label.

5204

"valueType": "A String", # The type of data that can be assigned to the label.

5205

"description": "A String", # A human-readable description for the label.

5206

"key": "A String", # The label key.

5207

},

5208

],

5209

"type": "A String", # The metric type including a DNS name prefix, for example

5210

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

5211

# should use a natural hierarchical grouping such as the following:

5212

#

5213

# compute.googleapis.com/instance/cpu/utilization

5214

# compute.googleapis.com/instance/disk/read_ops_count

5215

# compute.googleapis.com/instance/network/received_bytes_count

5216

#

5217

# Note that if the metric type changes, the monitoring data will be

5218

# discontinued, and anything depends on it will break, such as monitoring

5219

# dashboards, alerting rules and quota limits. Therefore, once a metric has

5220

# been published, its type should be immutable.

5221

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

5222

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

5223

# supported units are a subset of [The Unified Code for Units of

5224

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5225

#

5226

# **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)

5241

# * `P` peta (10**15)

5242

# * `E` exa (10**18)

5243

# * `Z` zetta (10**21)

5244

# * `Y` yotta (10**24)

5245

# * `m` milli (10**-3)

5246

# * `u` micro (10**-6)

5247

# * `n` nano (10**-9)

5248

# * `p` pico (10**-12)

5249

# * `f` femto (10**-15)

5250

# * `a` atto (10**-18)

5251

# * `z` zepto (10**-21)

5252

# * `y` yocto (10**-24)

5253

# * `Ki` kibi (2**10)

5254

# * `Mi` mebi (2**20)

5255

# * `Gi` gibi (2**30)

5256

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5261

#

5262

# The grammar also includes these connectors:

5263

#

5264

# * `/` division (as an infix operator, e.g. `1/s`).

5265

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5266

#

5267

# The grammar for a unit is as follows:

5268

#

5269

# Expression = Component { "." Component } { "/" Component } ;

5270

#

5271

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5281

# equivalent to `1` if it is used alone. For examples,

5282

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5283

# * `NAME` is a sequence of non-blank printable ASCII characters not

5284

# containing '{' or '}'.

5285

"name": "A String", # Resource name. The format of the name may vary between different

5286

# implementations. For examples:

5287

#

5288

# projects/{project_id}/metricDescriptors/{type=**}

5289

# metricDescriptors/{type=**}

5290

},

5291

],

5292

"enums": [ # A list of all enum types included in this API service. Enums

5293

# referenced directly or indirectly by the `apis` are automatically

5294

# included. Enums which are not referenced but shall be included

5295

# should be listed here by name. Example:

5296

#

5297

# enums:

5298

# - name: google.someapi.v1.SomeEnum

5299

{ # Enum type definition.

5300

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5301

# protobuf element, like the file in which it is defined.

5302

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5303

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5304

},

5305

"enumvalue": [ # Enum value definitions.

5306

{ # Enum value definition.

5307

"number": 42, # Enum value number.

5308

"options": [ # Protocol buffer options.

5309

{ # A protocol buffer option, which can be attached to a message, field,

5310

# enumeration, etc.

5311

"name": "A String", # The option's name. For example, `"java_package"`.

5312

"value": { # The option's value. For example, `"com.google.protobuf"`.

5313

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

5318

},

5319

],

5320

"options": [ # Protocol buffer options.

5321

{ # A protocol buffer option, which can be attached to a message, field,

5322

# enumeration, etc.

5323

"name": "A String", # The option's name. For example, `"java_package"`.

5324

"value": { # The option's value. For example, `"com.google.protobuf"`.

5325

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

5330

"syntax": "A String", # The source syntax.

5331

},

5332

],

5333

"types": [ # A list of all proto message types included in this API service.

5334

# Types referenced directly or indirectly by the `apis` are

5335

# automatically included. Messages which are not referenced but

5336

# shall be included, such as types used by the `google.protobuf.Any` type,

5337

# should be listed here by name. Example:

5338

#

5339

# types:

5340

# - name: google.protobuf.Int32

5341

{ # A protocol buffer message type.

5342

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5343

"A String",

5344

],

5345

"name": "A String", # The fully qualified message name.

5346

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5347

# protobuf element, like the file in which it is defined.

5348

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5349

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5350

},

5351

"syntax": "A String", # The source syntax.

5352

"fields": [ # The list of fields.

5353

{ # A single field of a message type.

5354

"kind": "A String", # The field type.

5355

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5356

# types. The first type has index 1; zero means the type is not in the list.

5357

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5358

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5359

"name": "A String", # The field name.

5360

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5361

"jsonName": "A String", # The field JSON name.

5362

"number": 42, # The field number.

5363

"cardinality": "A String", # The field cardinality.

5364

"options": [ # The protocol buffer options.

5365

{ # A protocol buffer option, which can be attached to a message, field,

5366

# enumeration, etc.

5367

"name": "A String", # The option's name. For example, `"java_package"`.

5368

"value": { # The option's value. For example, `"com.google.protobuf"`.

5369

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5374

},

5375

],

5376

"options": [ # The protocol buffer options.

5377

{ # A protocol buffer option, which can be attached to a message, field,

5378

# enumeration, etc.

5379

"name": "A String", # The option's name. For example, `"java_package"`.

5380

"value": { # The option's value. For example, `"com.google.protobuf"`.

5381

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5387

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5388

#

5389

# The following example shows how to configure logs to be sent to the

5390

# producer and consumer projects. In the example,

5391

# the `library.googleapis.com/activity_history` log is

5392

# sent to both the producer and consumer projects, whereas

5393

# the `library.googleapis.com/purchase_history` log is only sent to the

5394

# producer project:

5395

#

5396

# monitored_resources:

5397

# - type: library.googleapis.com/branch

5398

# labels:

5399

# - key: /city

5400

# description: The city where the library branch is located in.

5401

# - key: /name

5402

# description: The name of the branch.

5403

# logs:

5404

# - name: library.googleapis.com/activity_history

5405

# labels:

5406

# - key: /customer_id

5407

# - name: library.googleapis.com/purchase_history

5408

# logging:

5409

# producer_destinations:

5410

# - monitored_resource: library.googleapis.com/branch

5411

# logs:

5412

# - library.googleapis.com/activity_history

5413

# - library.googleapis.com/purchase_history

5414

# consumer_destinations:

5415

# - monitored_resource: library.googleapis.com/branch

5416

# logs:

5417

# - library.googleapis.com/activity_history

5418

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5419

# There can be multiple producer destinations, each one must have a

5420

# different monitored resource type. A log can be used in at most

5421

# one producer destination.

5422

{ # Configuration of a specific logging destination (the producer project

5423

# or the consumer project).

5424

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5425

# Service.monitored_resources section.

5426

"logs": [ # Names of the logs to be sent to this destination. Each name must

5427

# be defined in the Service.logs section.

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5433

# There can be multiple consumer destinations, each one must have a

5434

# different monitored resource type. A log can be used in at most

5435

# one consumer destination.

5436

{ # Configuration of a specific logging destination (the producer project

5437

# or the consumer project).

5438

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

5439

# Service.monitored_resources section.

5440

"logs": [ # Names of the logs to be sent to this destination. Each name must

5441

# be defined in the Service.logs section.

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

5448

# e.g. `calendar.googleapis.com`.

5449

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5450

#

5451

# Example:

5452

# <pre><code>documentation:

5453

# summary: >

5454

# The Google Calendar API gives access

5455

# to most calendar features.

5456

# pages:

5457

# - name: Overview

5458

# content: (== include google/foo/overview.md ==)

5459

# - name: Tutorial

5460

# content: (== include google/foo/tutorial.md ==)

5461

# subpages;

5462

# - name: Java

5463

# content: (== include google/foo/tutorial_java.md ==)

5464

# rules:

5465

# - selector: google.calendar.Calendar.Get

5466

# description: >

5467

# ...

5468

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5473

# standard markdown features, definition lists, tables and fenced

5474

# code blocks are supported. Section headers can be provided and are

5475

# interpreted relative to the section nesting of the context where

5476

# a documentation fragment is embedded.

5477

#

5478

# Documentation from the IDL is merged with documentation defined

5479

# via the config at normalization time, where documentation provided

5480

# by config rules overrides IDL provided.

5481

#

5482

# A number of constructs specific to the API platform are supported

5483

# in documentation text.

5484

#

5485

# In order to reference a proto element, the following

5486

# notation can be used:

5487

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5488

# To override the display text used for the link, this can be used:

5489

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5490

# Text can be excluded from doc using the following notation:

5491

# <pre><code>(-- internal comment --)</code></pre>

5492

# Comments can be made conditional using a visibility label. The below

5493

# text will be only rendered if the `BETA` label is available:

5494

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5495

# A few directives are available in documentation. Note that

5496

# directives must appear on a single line to be properly

5497

# identified. The `include` directive includes a markdown file from

5498

# an external source:

5499

# <pre><code>(== include path/to/file ==)</code></pre>

5500

# The `resource_for` directive marks a message to be the resource of

5501

# a collection in REST view. If it is not specified, tools attempt

5502

# to infer the resource from the operations in a collection:

5503

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5504

# The directive `suppress_warning` does not directly affect documentation

5505

# and is documented together with service config validation.

5506

"rules": [ # A list of documentation rules that apply to individual API elements.

5507

#

5508

# **NOTE:** All service configuration rules follow "last one wins" order.

5509

{ # A documentation rule provides information about individual API elements.

5510

"description": "A String", # Description of the selected API(s).

5511

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5512

# element is marked as `deprecated`.

5513

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5514

# qualified name of the element which may end in "*", indicating a wildcard.

5515

# Wildcards are only allowed at the end and for a whole component of the

5516

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5517

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

5522

# <pre><code>documentation:

5523

# summary: ...

5524

# overview: (== include overview.md ==)

5525

# </code></pre>

5526

# This is a shortcut for the following declaration (using pages style):

5527

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5532

# </code></pre>

5533

# Note: you cannot specify both `overview` field and `pages` field.

5534

"summary": "A String", # A short summary of what the service does. Can only be provided by

5535

# plain text.

5536

"pages": [ # The top level pages for the documentation set.

5537

{ # Represents a documentation page. A page can contain subpages to represent

5538

# nested documentation set structure.

5539

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5540

# to include content from a Markdown file.

5541

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5542

# honored in the generated docset.

5543

# Object with schema name: Page

5544

],

5545

"name": "A String", # The name of the page. It will be used as an identity of the page to

5546

# generate URI of the page, text of the link to this page in navigation,

5547

# etc. The full page name (start from the root page name to this page

5548

# concatenated with `.`) can be used as reference to the page in your

5549

# documentation. For example:

5550

# <pre><code>pages:

5551

# - name: Tutorial

5552

# content: (== include tutorial.md ==)

5553

# subpages:

5554

# - name: Java

5555

# content: (== include tutorial_java.md ==)

5556

# </code></pre>

5557

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

5562

},

5563

"systemTypes": [ # A list of all proto message types included in this API service.

5564

# It serves similar purpose as [google.api.Service.types], except that

5565

# these types are not needed by user-defined APIs. Therefore, they will not

5566

# show up in the generated discovery doc. This field should only be used

5567

# to define system APIs in ESF.

5568

{ # A protocol buffer message type.

5569

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5570

"A String",

5571

],

5572

"name": "A String", # The fully qualified message name.

5573

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5574

# protobuf element, like the file in which it is defined.

5575

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5576

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5577

},

5578

"syntax": "A String", # The source syntax.

5579

"fields": [ # The list of fields.

5580

{ # A single field of a message type.

5581

"kind": "A String", # The field type.

5582

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5583

# types. The first type has index 1; zero means the type is not in the list.

5584

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5585

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5586

"name": "A String", # The field name.

5587

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5588

"jsonName": "A String", # The field JSON name.

5589

"number": 42, # The field number.

5590

"cardinality": "A String", # The field cardinality.

5591

"options": [ # The protocol buffer options.

5592

{ # A protocol buffer option, which can be attached to a message, field,

5593

# enumeration, etc.

5594

"name": "A String", # The option's name. For example, `"java_package"`.

5595

"value": { # The option's value. For example, `"com.google.protobuf"`.

5596

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5601

},

5602

],

5603

"options": [ # The protocol buffer options.

5604

{ # A protocol buffer option, which can be attached to a message, field,

5605

# enumeration, etc.

5606

"name": "A String", # The option's name. For example, `"java_package"`.

5607

"value": { # The option's value. For example, `"com.google.protobuf"`.

5608

"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

5623

# - google.rpc.context.OriginContext

5624

#

5625

# The above specifies that all methods in the API request

5626

# `google.rpc.context.ProjectContext` and

5627

# `google.rpc.context.OriginContext`.

5628

#

5629

# Available context types are defined in package

5630

# `google.rpc.context`.

5631

"rules": [ # A list of RPC context rules that apply to individual API methods.

5632

#

5633

# **NOTE:** All service configuration rules follow "last one wins" order.

5634

{ # A context rule provides information about the context for an individual API

5635

# element.

5636

"provided": [ # A list of full type names of provided contexts.

5637

"A String",

5638

],

5639

"requested": [ # A list of full type names of requested contexts.

5640

"A String",

5641

],

5642

"selector": "A String", # Selects the methods to which this rule applies.

5643

#

5644

# Refer to selector for syntax details.

5645

},

5646

],

5647

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5648

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5649

# with the same name as the service is automatically generated to service all

5650

# defined APIs.

5651

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5652

# A service may expose any number of endpoints, and all endpoints share the

5653

# same service configuration, such as quota configuration and monitoring

5654

# configuration.

5655

#

5656

# Example service configuration:

5657

#

5658

# name: library-example.googleapis.com

5659

# endpoints:

5660

# # Below entry makes 'google.example.library.v1.Library'

5661

# # API be served from endpoint address library-example.googleapis.com.

5662

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5663

# # it to decide whether the subsequent cross-origin request is

5664

# # allowed to proceed.

5665

# - name: library-example.googleapis.com

5666

# apis: google.example.library.v1.Library

5667

# allow_cors: true

5668

# # Below entry makes 'google.example.library.v1.Library'

5669

# # API be served from endpoint address

5670

# # google.example.library-example.v1.LibraryManager.

5671

# - name: library-manager.googleapis.com

5672

# apis: google.example.library.v1.LibraryManager

5673

# # BNS address for a borg job. Can specify a task by appending

5674

# # "/taskId" (e.g. "/0") to the job spec.

5675

#

5676

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

5682

# },

5683

# "host": "MY_PROJECT_ID.appspot.com",

5684

# "x-google-endpoints": [{

5685

# "name": "MY_PROJECT_ID.appspot.com",

5686

# "allow_cors": "true"

5687

# }]

5688

# }

5689

"allowCors": True or False, # Allowing

5690

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5691

# cross-domain traffic, would allow the backends served from this endpoint to

5692

# receive and respond to HTTP OPTIONS requests. The response will be used by

5693

# the browser to determine whether the subsequent cross-origin request is

5694

# allowed to proceed.

5695

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

5696

# please specify multiple google.api.Endpoint for each of the intented

5697

# alias.

5698

#

5699

# Additional names that this endpoint will be hosted on.

5700

"A String",

5701

],

5702

"features": [ # The list of features enabled on this endpoint.

5703

"A String",

5704

],

5705

"name": "A String", # The canonical name of this endpoint.

5706

"apis": [ # The list of APIs served by this endpoint.

"A String",

],

},

],

Jon Wayne Parrott