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-21 13:59:49 -0700

[diff] [blame^]

195

"analytics": { # Analytics configuration of the service. # WARNING: DO NOT USE UNTIL THIS MESSAGE IS REMOVED.

196

#

197

# Analytics configuration.

198

#

199

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

200

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

201

# defined. The `library.googleapis.com/book/returned_count` and

202

# `library.googleapis.com/book/overdue_count` metric are sent

203

# to the analytics.

204

#

205

# monitored_resources:

206

# - type: library.googleapis.com/branch

207

# labels:

208

# - key: /city

209

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

210

# - key: /name

211

# description: The name of the branch.

212

# metrics:

213

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

218

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

223

# analytics:

224

# producer_destinations:

225

# - monitored_resource: library.googleapis.com/branch

226

# metrics:

227

# - library.googleapis.com/book/returned_count

228

# - library.googleapis.com/book/overdue_count

229

"producerDestinations": [ # Analytics configurations for sending metrics to the analytics backend.

230

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

231

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

232

# one producer destination.

233

{ # Configuration of a specific analytics destination.

234

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

235

# Service.monitored_resources section.

236

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

237

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

238

# with value type BOOL and STRING must be of GUAGE kind, metrics with

239

# value type INT64, DOUBLE and MONEY must be of DELTA kind.

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame]

245

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

Jon Wayne Parrott

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

[diff] [blame]

246

#

247

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

248

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

249

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

250

# change the names of the system parameters.

251

"rules": [ # Define system parameters.

252

#

253

# The parameters defined here will override the default parameters

254

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

255

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

256

# and names is implementation-dependent.

257

#

258

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

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

266

# - name: alt

267

# http_header: Response-Content-Type

268

#

269

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

274

# parameters:

275

# - name: api_key

276

# http_header: Api-Key1

277

# - name: api_key

278

# http_header: Api-Key2

279

#

280

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

281

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

282

# methods.

283

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

284

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

285

# names are used the behavior is implementation-dependent.

286

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

287

# parameter-dependent.

288

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

289

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

290

# is implementation-dependent.

291

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

292

# sensitive.

293

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

294

# and etc. It is case sensitive.

295

"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

300

# methods in all APIs.

301

#

302

# Refer to selector for syntax details.

},

],

},

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

307

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

308

#

309

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

310

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

311

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

312

#

313

# Refer to selector for syntax details.

314

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

315

# default depends on the deployment context.

316

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

317

},

318

],

319

},

Sai Cheemalapati

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

[diff] [blame]

320

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

Jon Wayne Parrott

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

[diff] [blame]

321

#

322

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

323

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

324

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

325

# to both producer and consumer projects, whereas the

326

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

327

# consumer project.

328

#

329

# monitored_resources:

330

# - type: library.googleapis.com/branch

331

# labels:

332

# - key: /city

333

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

334

# - key: /name

335

# description: The name of the branch.

336

# metrics:

337

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

342

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

347

# monitoring:

348

# producer_destinations:

349

# - monitored_resource: library.googleapis.com/branch

350

# metrics:

351

# - library.googleapis.com/book/returned_count

352

# consumer_destinations:

353

# - monitored_resource: library.googleapis.com/branch

354

# metrics:

355

# - library.googleapis.com/book/returned_count

356

# - library.googleapis.com/book/overdue_count

357

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

358

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

359

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

360

# one producer destination.

361

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

362

# or the consumer project).

363

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

364

# Service.monitored_resources section.

365

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

366

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

"A String",

],

},

],

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

372

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

373

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

374

# one consumer destination.

375

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

376

# or the consumer project).

377

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

378

# Service.monitored_resources section.

379

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

380

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

"A String",

],

},

],

},

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

387

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

388

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

389

# generate one instead.

390

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

391

#

392

# Example for an API targeted for external use:

393

#

394

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

400

#

401

# - selector: google.calendar.Delegate

402

# oauth:

403

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

404

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

405

#

406

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

407

{ # Authentication rules for the service.

408

#

409

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

410

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

411

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

412

# request.

413

#

414

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

415

# ignored.

416

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

417

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

418

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

419

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

420

#

421

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

422

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

423

#

424

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

425

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

426

# the OAuth scope across all of those APIs.

427

#

428

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

429

# management about how developers will use them in practice.

430

#

431

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

432

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

433

# due to the backend requiring additional scopes or permissions.

434

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

435

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

#

# Example:

#

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

440

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

441

},

442

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

443

{ # User-defined authentication requirements, including support for

444

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

445

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

#

# Example:

#

# provider_id: bookstore_auth

450

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

451

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

452

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

453

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

454

# "https://Service_name/API_name"

455

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

456

# LibraryService API will only accept JWTs with the following audience

457

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

462

# bookstore_web.apps.googleusercontent.com

463

},

464

],

Jon Wayne Parrott

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

[diff] [blame]

465

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

466

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

467

#

468

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

469

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

470

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

471

# project.

Jon Wayne Parrott

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

[diff] [blame]

472

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

473

#

474

# Refer to selector for syntax details.

475

},

476

],

477

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

478

{ # Configuration for an anthentication provider, including support for

479

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

480

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

481

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

482

# Optional if the key set document:

483

# - can be retrieved from

484

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

485

# of the issuer.

486

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

487

#

488

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

489

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

490

# `AuthRequirement.provider_id`.

491

#

492

# Example: "bookstore_auth".

493

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

494

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

495

# Usually a URL or an email address.

496

#

497

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

498

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

},

],

},

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

503

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

504

#

505

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

506

{ # Usage configuration rules for the service.

507

#

508

# NOTE: Under development.

509

#

510

#

511

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

512

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

513

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

514

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

515

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

516

# allow/disallow unregistered calls.

517

#

518

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

524

#

525

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

#

# usage:

# rules:

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

530

# allow_unregistered_calls: true

531

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

532

# methods in all APIs.

533

#

534

# Refer to selector for syntax details.

535

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

536

},

537

],

538

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

539

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

540

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

"A String",

],

},

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

545

# influence interpretation of the configuration, for example, to

546

# determine defaults. This is documented together with applicable

547

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

548

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

549

# Members of this project can manage the service configuration,

550

# manage consumption of the service, etc.

551

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

552

# HttpRule, each specifying the mapping of an RPC method

553

# to one or more HTTP REST API methods.

554

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

555

#

556

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

557

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

558

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

559

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

560

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

561

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

562

# for details.

563

#

564

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

565

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

566

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

567

# operation on a resource collection of messages:

568

#

569

# ```proto

570

# service Messaging {

571

# rpc GetMessage(GetMessageRequest) returns (Message) {

572

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

573

# }

574

# }

575

# message GetMessageRequest {

576

# message SubMessage {

577

# string subfield = 1;

578

# }

579

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

580

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

581

# }

582

# message Message {

583

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

588

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

593

#

594

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

595

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

596

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

597

#

598

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

599

# pattern automatically become (optional) HTTP query

600

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

601

#

602

# ```proto

603

# message GetMessageRequest {

604

# message SubMessage {

605

# string subfield = 1;

606

# }

607

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

608

# int64 revision = 2; // becomes a parameter

609

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

618

#

619

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

620

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

621

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

622

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

623

#

624

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

625

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

626

# message resource collection:

627

#

628

# ```proto

629

# service Messaging {

630

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

631

# option (google.api.http) = {

632

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

638

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

639

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

# }

# ```

#

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

644

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

645

# protos JSON encoding:

#

# HTTP | RPC

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

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

650

#

651

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

652

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

653

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

658

# rpc UpdateMessage(Message) returns (Message) {

659

# option (google.api.http) = {

660

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

676

#

677

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

678

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

679

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

680

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

681

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

682

#

683

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

684

# the `additional_bindings` option. Example:

685

#

686

# ```proto

687

# service Messaging {

688

# rpc GetMessage(GetMessageRequest) returns (Message) {

689

# option (google.api.http) = {

690

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

691

# additional_bindings {

692

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

# }

# };

# }

# }

# message GetMessageRequest {

698

# string message_id = 1;

699

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

709

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

710

#

711

# # Rules for HTTP mapping

712

#

713

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

714

# to the request message are as follows:

715

#

716

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

717

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

718

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

719

# request) can be classified into three types:

720

# (a) Matched in the URL template.

721

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

722

# else everything under the body field)

723

# (c) All other fields.

724

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

725

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

726

#

727

# The syntax of the path template is as follows:

728

#

729

# Template = "/" Segments [ Verb ] ;

730

# Segments = Segment { "/" Segment } ;

731

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

732

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

733

# FieldPath = IDENT { "." IDENT } ;

734

# Verb = ":" LITERAL ;

735

#

736

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

737

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

738

# Expansion.

739

#

740

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

741

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

742

# Expansion.

743

#

744

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

745

#

746

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

747

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

748

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

749

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

750

#

751

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

752

# repeated fields or map fields.

753

#

754

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

755

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

756

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

757

# content to Web (HTML) clients.

758

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

759

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

760

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

761

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

762

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

763

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

764

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

765

# configuration.

766

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

767

# configuration.

768

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

769

},

770

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

771

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

772

# the nesting may only be one level deep).

773

# Object with schema name: HttpRule

774

],

775

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

776

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

777

# configuration.

778

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

779

# configuration.

780

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

781

},

782

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

783

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

784

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

785

},

786

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

787

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

788

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

789

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

790

# at the top-level of response message type.

791

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

792

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

793

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

794

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

795

#

796

# Refer to selector for syntax details.

797

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

},

],

},

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

802

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

803

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

804

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

805

# which cannot be resolved against the associated IDL files.

806

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

807

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

808

{ # Method represents a method of an api.

809

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

810

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

811

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

812

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

813

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

814

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

815

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

816

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

817

# enumeration, etc.

818

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

819

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

820

"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

827

# message.

828

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

829

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

830

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

831

},

832

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

833

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

834

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

835

# and options are inherited as follows:

836

#

837

# - If after comment and whitespace stripping, the documentation

838

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

839

# from the original method.

840

#

841

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

842

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

843

# inherited.

844

#

845

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

846

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

847

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

848

#

849

# Example of a simple mixin:

850

#

851

# package google.acl.v1;

852

# service AccessControl {

853

# // Get the underlying ACL object.

854

# rpc GetAcl(GetAclRequest) returns (Acl) {

855

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

# }

# }

#

# package google.storage.v2;

860

# service Storage {

861

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

862

#

863

# // Get a data record.

864

# rpc GetData(GetDataRequest) returns (Data) {

865

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

# }

# }

#

# Example of a mixin configuration:

870

#

871

# apis:

872

# - name: google.storage.v2.Storage

873

# mixins:

874

# - name: google.acl.v1.AccessControl

875

#

876

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

877

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

878

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

879

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

880

# documentation and annotations as follows:

881

#

882

# service Storage {

883

# // Get the underlying ACL object.

884

# rpc GetAcl(GetAclRequest) returns (Acl) {

885

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

# }

# ...

# }

#

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

891

#

892

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

893

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

894

#

895

# apis:

896

# - name: google.storage.v2.Storage

897

# mixins:

898

# - name: google.acl.v1.AccessControl

899

# root: acls

900

#

901

# This implies the following inherited HTTP annotation:

902

#

903

# service Storage {

904

# // Get the underlying ACL object.

905

# rpc GetAcl(GetAclRequest) returns (Acl) {

906

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

# }

# ...

# }

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

911

# are rooted.

912

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

913

},

914

],

915

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

916

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

917

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

918

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

919

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

920

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

921

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

922

# provided here.

923

#

924

# The versioning schema uses [semantic

925

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

926

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

927

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

928

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

929

# chosen based on the product plan.

930

#

931

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

932

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

933

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

934

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

935

# experimental, none-GA apis.

936

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

937

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

938

# enumeration, etc.

939

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

940

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

941

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

},

},

],

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

946

# followed by the api's simple name.

947

},

948

],

949

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

950

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

958

# - google.foo.v1.AnotherError

959

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

960

#

961

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

962

{ # A custom error rule.

963

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

964

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

965

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

966

#

967

# Refer to selector for syntax details.

968

},

969

],

970

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

"A String",

],

},

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

975

# elements. Restrictions are specified using visibility labels

976

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

977

#

978

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

979

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

980

# elements, plus any unrestricted elements.

981

#

982

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

983

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

990

# restriction: TRUSTED_TESTER

991

# - selector: google.calendar.Calendar.Delegate

992

# restriction: GOOGLE_INTERNAL

993

#

994

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

995

# EnhancedSearch and Delegate.

996

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

997

#

998

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

999

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

1000

# element.

Sai Cheemalapati

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

[diff] [blame]

1001

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

1002

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

Jon Wayne Parrott

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

[diff] [blame]

1003

#

1004

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

1005

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1012

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1013

#

1014

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1015

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

1016

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

1017

#

1018

# Refer to selector for syntax details.

},

],

},

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

1023

{ # Defines a metric type and its schema.

1024

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

1025

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

1026

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

1027

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

1028

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

Jon Wayne Parrott

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

[diff] [blame]

1029

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

1030

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

Jon Wayne Parrott

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

[diff] [blame]

1031

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

1032

# metric type. For example, the

1033

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

1034

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

1035

# received through a load balanced IP address.

1036

{ # A description of a label.

1037

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

1038

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

1039

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

1040

},

1041

],

1042

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

1043

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

1044

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

1045

#

1046

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

1047

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

1048

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

1049

#

1050

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

1051

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

1052

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

1053

# been published, its type should be immutable.

1054

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

1055

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

1056

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

1057

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

1058

#

1059

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

1074

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

1075

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

1076

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

1077

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

1078

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

1079

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

1080

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

1081

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

1082

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

1083

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

1084

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

1085

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

1086

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

1087

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

1088

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

1089

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

#

# **Grammar**

#

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

1094

#

1095

# The grammar also includes these connectors:

1096

#

1097

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

1098

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

1099

#

1100

# The grammar for a unit is as follows:

1101

#

1102

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

1103

#

1104

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1114

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

1115

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

1116

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

1117

# containing '{' or '}'.

1118

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

1119

# implementations. For examples:

1120

#

1121

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

1122

# metricDescriptors/{type=**}

1123

},

1124

],

1125

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

1126

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

1127

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

1128

# should be listed here by name. Example:

1129

#

1130

# enums:

1131

# - name: google.someapi.v1.SomeEnum

1132

{ # Enum type definition.

1133

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

1134

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

1135

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

1136

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

1137

},

1138

"enumvalue": [ # Enum value definitions.

1139

{ # Enum value definition.

1140

"number": 42, # Enum value number.

1141

"options": [ # Protocol buffer options.

1142

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

1143

# enumeration, etc.

1144

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

1145

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

1146

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

},

},

],

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

1151

},

1152

],

1153

"options": [ # Protocol buffer options.

1154

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

1155

# enumeration, etc.

1156

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

1157

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

1158

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

},

},

],

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

1163

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

1164

},

1165

],

1166

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

1167

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

1168

# automatically included. Messages which are not referenced but

1169

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

1170

# should be listed here by name. Example:

1171

#

1172

# types:

1173

# - name: google.protobuf.Int32

1174

{ # A protocol buffer message type.

1175

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

1176

"A String",

1177

],

1178

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

1179

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

1180

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

1181

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

1182

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

1183

},

1184

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

1185

"fields": [ # The list of fields.

1186

{ # A single field of a message type.

1187

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

1188

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

1189

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

1190

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

1191

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

1192

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

1193

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

1194

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

1195

"number": 42, # The field number.

1196

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

1197

"options": [ # The protocol buffer options.

1198

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

1199

# enumeration, etc.

1200

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

1201

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

1202

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

},

},

],

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

1207

},

1208

],

1209

"options": [ # The protocol buffer options.

1210

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

1211

# enumeration, etc.

1212

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

1213

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

1214

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1220

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

Jon Wayne Parrott

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

[diff] [blame]

1221

#

1222

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

Sai Cheemalapati

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

[diff] [blame^]

1223

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

1224

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

1225

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

Jon Wayne Parrott

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

[diff] [blame]

1226

#

1227

# monitored_resources:

1228

# - type: library.googleapis.com/branch

1229

# labels:

1230

# - key: /city

1231

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

1232

# - key: /name

1233

# description: The name of the branch.

1234

# logs:

Sai Cheemalapati

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

[diff] [blame^]

1235

# - name: activity_history

Jon Wayne Parrott

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

[diff] [blame]

1236

# labels:

1237

# - key: /customer_id

Sai Cheemalapati

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

[diff] [blame^]

1238

# - name: purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1239

# logging:

1240

# producer_destinations:

1241

# - monitored_resource: library.googleapis.com/branch

1242

# logs:

Sai Cheemalapati

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

[diff] [blame^]

1243

# - activity_history

1244

# - purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1245

# consumer_destinations:

1246

# - monitored_resource: library.googleapis.com/branch

1247

# logs:

Sai Cheemalapati

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

[diff] [blame^]

1248

# - activity_history

Jon Wayne Parrott

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

[diff] [blame]

1249

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

1250

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

1251

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

1252

# one producer destination.

1253

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

1254

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame^]

1255

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

Jon Wayne Parrott

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

[diff] [blame]

1256

# Service.monitored_resources section.

1257

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

Sai Cheemalapati

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

[diff] [blame^]

1258

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

1259

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

1260

# the service name followed by "/".

Jon Wayne Parrott

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

[diff] [blame]

"A String",

],

},

],

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

1266

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

1267

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

1268

# one consumer destination.

1269

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

1270

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame^]

1271

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

Jon Wayne Parrott

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

[diff] [blame]

1272

# Service.monitored_resources section.

1273

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

Sai Cheemalapati

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

[diff] [blame^]

1274

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

1275

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

1276

# the service name followed by "/".

Jon Wayne Parrott

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

[diff] [blame]

"A String",

],

},

],

},

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

1283

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

1284

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

1285

#

1286

# Example:

1287

# <pre><code>documentation:

1288

# summary: >

1289

# The Google Calendar API gives access

1290

# to most calendar features.

1291

# pages:

1292

# - name: Overview

1293

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

1294

# - name: Tutorial

1295

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

1296

# subpages;

1297

# - name: Java

1298

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

1299

# rules:

1300

# - selector: google.calendar.Calendar.Get

1301

# description: >

1302

# ...

1303

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1308

# standard markdown features, definition lists, tables and fenced

1309

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

1310

# interpreted relative to the section nesting of the context where

1311

# a documentation fragment is embedded.

1312

#

1313

# Documentation from the IDL is merged with documentation defined

1314

# via the config at normalization time, where documentation provided

1315

# by config rules overrides IDL provided.

1316

#

1317

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

1318

# in documentation text.

1319

#

1320

# In order to reference a proto element, the following

1321

# notation can be used:

1322

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

1323

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

1324

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

1325

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

1326

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

1327

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

1328

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

1329

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

1330

# A few directives are available in documentation. Note that

1331

# directives must appear on a single line to be properly

1332

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

1333

# an external source:

1334

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

1335

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

1336

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

1337

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

1338

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

1339

# The directive `suppress_warning` does not directly affect documentation

1340

# and is documented together with service config validation.

1341

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

1342

#

1343

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

1344

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

1345

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

1346

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

1347

# element is marked as `deprecated`.

1348

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

1349

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

1350

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

1351

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

1352

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

# is used.

},

],

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

1357

# <pre><code>documentation:

1358

# summary: ...

1359

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

1360

# </code></pre>

1361

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

1362

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1367

# </code></pre>

1368

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

1369

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

1370

# plain text.

1371

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

1372

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

1373

# nested documentation set structure.

1374

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

1375

# to include content from a Markdown file.

1376

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

1377

# honored in the generated docset.

1378

# Object with schema name: Page

1379

],

1380

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

1381

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

1382

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

1383

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

1384

# documentation. For example:

1385

# <pre><code>pages:

1386

# - name: Tutorial

1387

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

1388

# subpages:

1389

# - name: Java

1390

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

1391

# </code></pre>

1392

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

# `Java`.

},

],

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

1397

},

1398

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

1399

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

1400

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

1401

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

1402

# to define system APIs in ESF.

1403

{ # A protocol buffer message type.

1404

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

1405

"A String",

1406

],

1407

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

1408

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

1409

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

1410

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

1411

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

1412

},

1413

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

1414

"fields": [ # The list of fields.

1415

{ # A single field of a message type.

1416

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

1417

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

1418

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

1419

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

1420

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

1421

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

1422

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

1423

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

1424

"number": 42, # The field number.

1425

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

1426

"options": [ # The protocol buffer options.

1427

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

1428

# enumeration, etc.

1429

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

1430

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

1431

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

},

},

],

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

1436

},

1437

],

1438

"options": [ # The protocol buffer options.

1439

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

1440

# enumeration, etc.

1441

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

1442

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

1443

"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

1458

# - google.rpc.context.OriginContext

1459

#

1460

# The above specifies that all methods in the API request

1461

# `google.rpc.context.ProjectContext` and

1462

# `google.rpc.context.OriginContext`.

1463

#

1464

# Available context types are defined in package

1465

# `google.rpc.context`.

1466

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

1467

#

1468

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

1469

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

1470

# element.

1471

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

1472

"A String",

1473

],

1474

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

1475

"A String",

1476

],

1477

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

1478

#

1479

# Refer to selector for syntax details.

1480

},

1481

],

1482

},

Sai Cheemalapati

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

[diff] [blame]

1483

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

1484

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

1485

# defined APIs.

1486

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

1487

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

1488

# same service configuration, such as quota configuration and monitoring

1489

# configuration.

1490

#

1491

# Example service configuration:

1492

#

1493

# name: library-example.googleapis.com

1494

# endpoints:

1495

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

1496

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

1497

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

1498

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

1499

# # allowed to proceed.

1500

# - name: library-example.googleapis.com

1501

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

1502

# allow_cors: true

1503

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

1504

# # API be served from endpoint address

1505

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

1506

# - name: library-manager.googleapis.com

1507

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

1508

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

1509

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

1510

#

1511

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

#

# {

# "swagger": "2.0",

# "info": {

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

1517

# },

1518

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

1519

# "x-google-endpoints": [{

1520

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

1521

# "allow_cors": "true"

1522

# }]

1523

# }

1524

"allowCors": True or False, # Allowing

1525

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

1526

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

1527

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

1528

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

1529

# allowed to proceed.

1530

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

1531

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

1532

# alias.

1533

#

1534

# Additional names that this endpoint will be hosted on.

1535

"A String",

1536

],

1537

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

1538

"A String",

1539

],

1540

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

1541

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

"A String",

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1546

}

1547

1548

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1555

Sai Cheemalapati

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

[diff] [blame]

1556

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

1557

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

1558

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

1559

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

1560

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

1565

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

1566

# name: calendar.googleapis.com

1567

# title: Google Calendar API

1568

# apis:

Sai Cheemalapati

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

[diff] [blame]

1569

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame]

1570

# backend:

1571

# rules:

Sai Cheemalapati

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

[diff] [blame]

1572

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

Jon Wayne Parrott

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

[diff] [blame]

1573

# address: calendar.example.com

1574

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

1575

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

1576

# monitoring, etc.

1577

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

1578

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

1579

},

1580

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

1581

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

1582

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

1583

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

1584

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

1585

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

1586

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

1587

#

1588

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

1589

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

1590

# by the API.

1591

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

1592

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

1593

# The maximum length of this value is 256 characters.

1594

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

1595

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

1596

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

1597

{ # A description of a label.

1598

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

1599

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

1600

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

1601

},

1602

],

1603

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

1604

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

1605

# without any article or other determiners. For example,

1606

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

1607

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

1608

# be used in documentation.

1609

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

1610

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

1611

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

1612

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

1613

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

1614

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

1615

},

1616

],

1617

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

1618

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

1619

#

1620

# - name: library.googleapis.com/activity_history

1621

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

1622

# display_name: Activity

1623

# labels:

1624

# - key: /customer_id

1625

# description: Identifier of a library customer

1626

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

1627

# Runtime requests that contain labels not specified here are

1628

# considered invalid.

1629

{ # A description of a label.

1630

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

1631

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

1632

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

1633

},

1634

],

1635

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

1636

# the user interface and should be concise.

1637

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

1638

# the documentation and can contain details.

1639

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

1640

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

1641

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

1642

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

1643

},

1644

],

Sai Cheemalapati

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

[diff] [blame^]

1645

"analytics": { # Analytics configuration of the service. # WARNING: DO NOT USE UNTIL THIS MESSAGE IS REMOVED.

1646

#

1647

# Analytics configuration.

1648

#

1649

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

1650

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

1651

# defined. The `library.googleapis.com/book/returned_count` and

1652

# `library.googleapis.com/book/overdue_count` metric are sent

1653

# to the analytics.

1654

#

1655

# monitored_resources:

1656

# - type: library.googleapis.com/branch

1657

# labels:

1658

# - key: /city

1659

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

1660

# - key: /name

1661

# description: The name of the branch.

1662

# metrics:

1663

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1668

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1673

# analytics:

1674

# producer_destinations:

1675

# - monitored_resource: library.googleapis.com/branch

1676

# metrics:

1677

# - library.googleapis.com/book/returned_count

1678

# - library.googleapis.com/book/overdue_count

1679

"producerDestinations": [ # Analytics configurations for sending metrics to the analytics backend.

1680

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

1681

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

1682

# one producer destination.

1683

{ # Configuration of a specific analytics destination.

1684

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

1685

# Service.monitored_resources section.

1686

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

1687

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

1688

# with value type BOOL and STRING must be of GUAGE kind, metrics with

1689

# value type INT64, DOUBLE and MONEY must be of DELTA kind.

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame]

1695

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

Jon Wayne Parrott

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

[diff] [blame]

1696

#

1697

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

1698

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

1699

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

1700

# change the names of the system parameters.

1701

"rules": [ # Define system parameters.

1702

#

1703

# The parameters defined here will override the default parameters

1704

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

1705

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

1706

# and names is implementation-dependent.

1707

#

1708

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

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1716

# - name: alt

1717

# http_header: Response-Content-Type

1718

#

1719

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

1724

# parameters:

1725

# - name: api_key

1726

# http_header: Api-Key1

1727

# - name: api_key

1728

# http_header: Api-Key2

1729

#

1730

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

1731

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

1732

# methods.

1733

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

1734

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

1735

# names are used the behavior is implementation-dependent.

1736

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

1737

# parameter-dependent.

1738

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

1739

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

1740

# is implementation-dependent.

1741

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

1742

# sensitive.

1743

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

1744

# and etc. It is case sensitive.

1745

"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

1750

# methods in all APIs.

1751

#

1752

# Refer to selector for syntax details.

},

],

},

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

1757

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

1758

#

1759

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

1760

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

1761

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

1762

#

1763

# Refer to selector for syntax details.

1764

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

1765

# default depends on the deployment context.

1766

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

1767

},

1768

],

1769

},

Sai Cheemalapati

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

[diff] [blame]

1770

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

Jon Wayne Parrott

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

[diff] [blame]

1771

#

1772

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

1773

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

1774

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

1775

# to both producer and consumer projects, whereas the

1776

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

1777

# consumer project.

1778

#

1779

# monitored_resources:

1780

# - type: library.googleapis.com/branch

1781

# labels:

1782

# - key: /city

1783

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

1784

# - key: /name

1785

# description: The name of the branch.

1786

# metrics:

1787

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1792

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1797

# monitoring:

1798

# producer_destinations:

1799

# - monitored_resource: library.googleapis.com/branch

1800

# metrics:

1801

# - library.googleapis.com/book/returned_count

1802

# consumer_destinations:

1803

# - monitored_resource: library.googleapis.com/branch

1804

# metrics:

1805

# - library.googleapis.com/book/returned_count

1806

# - library.googleapis.com/book/overdue_count

1807

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

1808

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

1809

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

1810

# one producer destination.

1811

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

1812

# or the consumer project).

1813

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

1814

# Service.monitored_resources section.

1815

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

1816

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

"A String",

],

},

],

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

1822

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

1823

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

1824

# one consumer destination.

1825

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

1826

# or the consumer project).

1827

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

1828

# Service.monitored_resources section.

1829

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

1830

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

"A String",

],

},

],

},

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

1837

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

1838

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

1839

# generate one instead.

1840

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

1841

#

1842

# Example for an API targeted for external use:

1843

#

1844

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

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

1850

#

1851

# - selector: google.calendar.Delegate

1852

# oauth:

1853

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

1854

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

1855

#

1856

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

1857

{ # Authentication rules for the service.

1858

#

1859

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

1860

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

1861

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

1862

# request.

1863

#

1864

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

1865

# ignored.

1866

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

1867

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

1868

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

1869

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

1870

#

1871

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

1872

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

1873

#

1874

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

1875

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

1876

# the OAuth scope across all of those APIs.

1877

#

1878

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

1879

# management about how developers will use them in practice.

1880

#

1881

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

1882

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

1883

# due to the backend requiring additional scopes or permissions.

1884

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

1885

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

#

# Example:

#

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

1890

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

1891

},

1892

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

1893

{ # User-defined authentication requirements, including support for

1894

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

1895

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

#

# Example:

#

# provider_id: bookstore_auth

1900

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

1901

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

1902

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

1903

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

1904

# "https://Service_name/API_name"

1905

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

1906

# LibraryService API will only accept JWTs with the following audience

1907

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1912

# bookstore_web.apps.googleusercontent.com

1913

},

1914

],

Jon Wayne Parrott

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

[diff] [blame]

1915

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

1916

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

1917

#

1918

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

1919

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

1920

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

1921

# project.

Jon Wayne Parrott

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

[diff] [blame]

1922

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

1923

#

1924

# Refer to selector for syntax details.

1925

},

1926

],

1927

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

1928

{ # Configuration for an anthentication provider, including support for

1929

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

1930

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

1931

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

1932

# Optional if the key set document:

1933

# - can be retrieved from

1934

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

1935

# of the issuer.

1936

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

1937

#

1938

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

1939

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

1940

# `AuthRequirement.provider_id`.

1941

#

1942

# Example: "bookstore_auth".

1943

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

1944

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

1945

# Usually a URL or an email address.

1946

#

1947

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

1948

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

},

],

},

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

1953

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

1954

#

1955

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

1956

{ # Usage configuration rules for the service.

1957

#

1958

# NOTE: Under development.

1959

#

1960

#

1961

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

1962

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

1963

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

1964

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

1965

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

1966

# allow/disallow unregistered calls.

1967

#

1968

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1974

#

1975

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

#

# usage:

# rules:

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

1980

# allow_unregistered_calls: true

1981

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

1982

# methods in all APIs.

1983

#

1984

# Refer to selector for syntax details.

1985

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

1986

},

1987

],

1988

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

1989

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

1990

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

"A String",

],

},

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

1995

# influence interpretation of the configuration, for example, to

1996

# determine defaults. This is documented together with applicable

1997

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

1998

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

1999

# Members of this project can manage the service configuration,

2000

# manage consumption of the service, etc.

2001

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

2002

# HttpRule, each specifying the mapping of an RPC method

2003

# to one or more HTTP REST API methods.

2004

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

2005

#

2006

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

2007

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

2008

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

2009

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

2010

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

2011

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

2012

# for details.

2013

#

2014

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

2015

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

2016

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

2017

# operation on a resource collection of messages:

2018

#

2019

# ```proto

2020

# service Messaging {

2021

# rpc GetMessage(GetMessageRequest) returns (Message) {

2022

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

2023

# }

2024

# }

2025

# message GetMessageRequest {

2026

# message SubMessage {

2027

# string subfield = 1;

2028

# }

2029

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

2030

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

2031

# }

2032

# message Message {

2033

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

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

2038

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

2043

#

2044

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

2045

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

2046

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

2047

#

2048

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

2049

# pattern automatically become (optional) HTTP query

2050

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

2051

#

2052

# ```proto

2053

# message GetMessageRequest {

2054

# message SubMessage {

2055

# string subfield = 1;

2056

# }

2057

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

2058

# int64 revision = 2; // becomes a parameter

2059

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

2068

#

2069

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

2070

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

2071

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

2072

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

2073

#

2074

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

2075

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

2076

# message resource collection:

2077

#

2078

# ```proto

2079

# service Messaging {

2080

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2081

# option (google.api.http) = {

2082

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2088

# string message_id = 1; // mapped to the URL

2089

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

2094

# representation of the JSON in the request body is determined by

2095

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

2100

#

2101

# The special name `*` can be used in the body mapping to define that

2102

# every field not bound by the path template should be mapped to the

2103

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

2108

# rpc UpdateMessage(Message) returns (Message) {

2109

# option (google.api.http) = {

2110

# 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!")`

2126

#

2127

# Note that when using `*` in the body mapping, it is not possible to

2128

# have HTTP parameters, as all fields not bound by the path end in

2129

# the body. This makes this option more rarely used in practice of

2130

# defining REST APIs. The common usage of `*` is in custom methods

2131

# which don't use the URL at all for transferring data.

2132

#

2133

# It is possible to define multiple HTTP methods for one RPC by using

2134

# the `additional_bindings` option. Example:

2135

#

2136

# ```proto

2137

# service Messaging {

2138

# rpc GetMessage(GetMessageRequest) returns (Message) {

2139

# option (google.api.http) = {

2140

# get: "/v1/messages/{message_id}"

2141

# additional_bindings {

2142

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

2148

# string message_id = 1;

2149

# 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")`

2159

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

2160

#

2161

# # Rules for HTTP mapping

2162

#

2163

# The rules for mapping HTTP path, query parameters, and body fields

2164

# to the request message are as follows:

2165

#

2166

# 1. The `body` field specifies either `*` or a field path, or is

2167

# omitted. If omitted, it assumes there is no HTTP body.

2168

# 2. Leaf fields (recursive expansion of nested messages in the

2169

# request) can be classified into three types:

2170

# (a) Matched in the URL template.

2171

# (b) Covered by body (if body is `*`, everything except (a) fields;

2172

# else everything under the body field)

2173

# (c) All other fields.

2174

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

2175

# 4. Any body sent with an HTTP request can contain only (b) fields.

2176

#

2177

# The syntax of the path template is as follows:

2178

#

2179

# Template = "/" Segments [ Verb ] ;

2180

# Segments = Segment { "/" Segment } ;

2181

# Segment = "*" | "**" | LITERAL | Variable ;

2182

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2183

# FieldPath = IDENT { "." IDENT } ;

2184

# Verb = ":" LITERAL ;

2185

#

2186

# The syntax `*` matches a single path segment. It follows the semantics of

2187

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2188

# Expansion.

2189

#

2190

# The syntax `**` matches zero or more path segments. It follows the semantics

2191

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

2192

# Expansion.

2193

#

2194

# The syntax `LITERAL` matches literal text in the URL path.

2195

#

2196

# The syntax `Variable` matches the entire path as specified by its template;

2197

# this nested template must not contain further variables. If a variable

2198

# matches a single path segment, its template may be omitted, e.g. `{var}`

2199

# is equivalent to `{var=*}`.

2200

#

2201

# NOTE: the field paths in variables and in the `body` must not refer to

2202

# repeated fields or map fields.

2203

#

2204

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2205

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2206

# a given URL path rule. The wild-card rule is useful for services that provide

2207

# content to Web (HTML) clients.

2208

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2209

# `*` for mapping all fields not captured by the path pattern to the HTTP

2210

# body. NOTE: the referred field must not be a repeated field and must be

2211

# present at the top-level of response message type.

2212

"get": "A String", # Used for listing and getting information about resources.

2213

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2214

# [][google.bytestream.RestByteStream] as an API to your

2215

# configuration.

2216

# [][google.bytestream.RestByteStream] as an API to your

2217

# configuration.

2218

"enabled": True or False, # Whether download is enabled.

2219

},

2220

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2221

# not contain an `additional_bindings` field themselves (that is,

2222

# the nesting may only be one level deep).

2223

# Object with schema name: HttpRule

2224

],

2225

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2226

# [][google.bytestream.RestByteStream] as an API to your

2227

# configuration.

2228

# [][google.bytestream.RestByteStream] as an API to your

2229

# configuration.

2230

"enabled": True or False, # Whether upload is enabled.

2231

},

2232

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2233

"path": "A String", # The path matched by this custom verb.

2234

"kind": "A String", # The name of this custom HTTP verb.

2235

},

2236

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2237

# response. Other response fields are ignored. This field is optional. When

2238

# not set, the response message will be used as HTTP body of response.

2239

# NOTE: the referred field must be not a repeated field and must be present

2240

# at the top-level of response message type.

2241

"put": "A String", # Used for updating a resource.

2242

"patch": "A String", # Used for updating a resource.

2243

"post": "A String", # Used for creating a resource.

2244

"selector": "A String", # Selects methods to which this rule applies.

2245

#

2246

# Refer to selector for syntax details.

2247

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2252

# of the google.protobuf.Api needs to be provided by the configuration

2253

# author, as the remaining fields will be derived from the IDL during the

2254

# normalization process. It is an error to specify an API interface here

2255

# which cannot be resolved against the associated IDL files.

2256

{ # Api is a light-weight descriptor for a protocol buffer service.

2257

"methods": [ # The methods of this api, in unspecified order.

2258

{ # Method represents a method of an api.

2259

"name": "A String", # The simple name of this method.

2260

"requestStreaming": True or False, # If true, the request is streamed.

2261

"responseTypeUrl": "A String", # The URL of the output message type.

2262

"requestTypeUrl": "A String", # A URL of the input message type.

2263

"responseStreaming": True or False, # If true, the response is streamed.

2264

"syntax": "A String", # The source syntax of this method.

2265

"options": [ # Any metadata attached to the method.

2266

{ # A protocol buffer option, which can be attached to a message, field,

2267

# enumeration, etc.

2268

"name": "A String", # The option's name. For example, `"java_package"`.

2269

"value": { # The option's value. For example, `"com.google.protobuf"`.

2270

"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

2277

# message.

2278

# protobuf element, like the file in which it is defined.

2279

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2280

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2281

},

2282

"mixins": [ # Included APIs. See Mixin.

2283

{ # Declares an API to be included in this API. The including API must

2284

# redeclare all the methods from the included API, but documentation

2285

# and options are inherited as follows:

2286

#

2287

# - If after comment and whitespace stripping, the documentation

2288

# string of the redeclared method is empty, it will be inherited

2289

# from the original method.

2290

#

2291

# - Each annotation belonging to the service config (http,

2292

# visibility) which is not set in the redeclared method will be

2293

# inherited.

2294

#

2295

# - If an http annotation is inherited, the path pattern will be

2296

# modified as follows. Any version prefix will be replaced by the

2297

# version of the including API plus the root path if specified.

2298

#

2299

# Example of a simple mixin:

2300

#

2301

# package google.acl.v1;

2302

# service AccessControl {

2303

# // Get the underlying ACL object.

2304

# rpc GetAcl(GetAclRequest) returns (Acl) {

2305

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2310

# service Storage {

2311

# // rpc GetAcl(GetAclRequest) returns (Acl);

2312

#

2313

# // Get a data record.

2314

# rpc GetData(GetDataRequest) returns (Data) {

2315

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2320

#

2321

# apis:

2322

# - name: google.storage.v2.Storage

2323

# mixins:

2324

# - name: google.acl.v1.AccessControl

2325

#

2326

# The mixin construct implies that all methods in `AccessControl` are

2327

# also declared with same name and request/response types in

2328

# `Storage`. A documentation generator or annotation processor will

2329

# see the effective `Storage.GetAcl` method after inherting

2330

# documentation and annotations as follows:

2331

#

2332

# service Storage {

2333

# // Get the underlying ACL object.

2334

# rpc GetAcl(GetAclRequest) returns (Acl) {

2335

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2341

#

2342

# If the `root` field in the mixin is specified, it should be a

2343

# relative path under which inherited HTTP paths are placed. Example:

2344

#

2345

# apis:

2346

# - name: google.storage.v2.Storage

2347

# mixins:

2348

# - name: google.acl.v1.AccessControl

2349

# root: acls

2350

#

2351

# This implies the following inherited HTTP annotation:

2352

#

2353

# service Storage {

2354

# // Get the underlying ACL object.

2355

# rpc GetAcl(GetAclRequest) returns (Acl) {

2356

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2361

# are rooted.

2362

"name": "A String", # The fully qualified name of the API which is included.

2363

},

2364

],

2365

"syntax": "A String", # The source syntax of the service.

2366

"version": "A String", # A version string for this api. If specified, must have the form

2367

# `major-version.minor-version`, as in `1.10`. If the minor version

2368

# is omitted, it defaults to zero. If the entire version field is

2369

# empty, the major version is derived from the package name, as

2370

# outlined below. If the field is not empty, the version in the

2371

# package name will be verified to be consistent with what is

2372

# provided here.

2373

#

2374

# The versioning schema uses [semantic

2375

# versioning](http://semver.org) where the major version number

2376

# indicates a breaking change and the minor version an additive,

2377

# non-breaking change. Both version numbers are signals to users

2378

# what to expect from different versions, and should be carefully

2379

# chosen based on the product plan.

2380

#

2381

# The major version is also reflected in the package name of the

2382

# API, which must end in `v<major-version>`, as in

2383

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2384

# be omitted. Zero major versions must only be used for

2385

# experimental, none-GA apis.

2386

"options": [ # Any metadata attached to the API.

2387

{ # A protocol buffer option, which can be attached to a message, field,

2388

# enumeration, etc.

2389

"name": "A String", # The option's name. For example, `"java_package"`.

2390

"value": { # The option's value. For example, `"com.google.protobuf"`.

2391

"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

2396

# followed by the api's simple name.

2397

},

2398

],

2399

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2400

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2408

# - google.foo.v1.AnotherError

2409

"rules": [ # The list of custom error rules that apply to individual API messages.

2410

#

2411

# **NOTE:** All service configuration rules follow "last one wins" order.

2412

{ # A custom error rule.

2413

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2414

# objects of this type will be filtered when they appear in error payload.

2415

"selector": "A String", # Selects messages to which this rule applies.

2416

#

2417

# Refer to selector for syntax details.

2418

},

2419

],

2420

"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.

2425

# elements. Restrictions are specified using visibility labels

2426

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2427

#

2428

# Users and projects can have access to more than one visibility label. The

2429

# effective visibility for multiple labels is the union of each label's

2430

# elements, plus any unrestricted elements.

2431

#

2432

# If an element and its parents have no restrictions, visibility is

2433

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2440

# restriction: TRUSTED_TESTER

2441

# - selector: google.calendar.Calendar.Delegate

2442

# restriction: GOOGLE_INTERNAL

2443

#

2444

# Here, all methods are publicly visible except for the restricted methods

2445

# EnhancedSearch and Delegate.

2446

"rules": [ # A list of visibility rules that apply to individual API elements.

2447

#

2448

# **NOTE:** All service configuration rules follow "last one wins" order.

2449

{ # A visibility rule provides visibility configuration for an individual API

2450

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2451

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

2452

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2453

#

2454

# If a rule has multiple labels, removing one of the labels but not all of

2455

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2462

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2463

#

2464

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2465

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2466

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2467

#

2468

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

2473

{ # Defines a metric type and its schema.

2474

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2475

# Use sentence case without an ending period, for example "Request count".

2476

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2477

"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]

2478

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2479

"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]

2480

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2481

"labels": [ # The set of labels that can be used to describe a specific instance of this

2482

# metric type. For example, the

2483

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

2484

# has a label, `loadbalanced`, that specifies whether the traffic was

2485

# received through a load balanced IP address.

2486

{ # A description of a label.

2487

"valueType": "A String", # The type of data that can be assigned to the label.

2488

"description": "A String", # A human-readable description for the label.

2489

"key": "A String", # The label key.

2490

},

2491

],

2492

"type": "A String", # The metric type including a DNS name prefix, for example

2493

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

2494

# should use a natural hierarchical grouping such as the following:

2495

#

2496

# compute.googleapis.com/instance/cpu/utilization

2497

# compute.googleapis.com/instance/disk/read_ops_count

2498

# compute.googleapis.com/instance/network/received_bytes_count

2499

#

2500

# Note that if the metric type changes, the monitoring data will be

2501

# discontinued, and anything depends on it will break, such as monitoring

2502

# dashboards, alerting rules and quota limits. Therefore, once a metric has

2503

# been published, its type should be immutable.

2504

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2505

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2506

# supported units are a subset of [The Unified Code for Units of

2507

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2508

#

2509

# **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)

2524

# * `P` peta (10**15)

2525

# * `E` exa (10**18)

2526

# * `Z` zetta (10**21)

2527

# * `Y` yotta (10**24)

2528

# * `m` milli (10**-3)

2529

# * `u` micro (10**-6)

2530

# * `n` nano (10**-9)

2531

# * `p` pico (10**-12)

2532

# * `f` femto (10**-15)

2533

# * `a` atto (10**-18)

2534

# * `z` zepto (10**-21)

2535

# * `y` yocto (10**-24)

2536

# * `Ki` kibi (2**10)

2537

# * `Mi` mebi (2**20)

2538

# * `Gi` gibi (2**30)

2539

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2544

#

2545

# The grammar also includes these connectors:

2546

#

2547

# * `/` division (as an infix operator, e.g. `1/s`).

2548

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2549

#

2550

# The grammar for a unit is as follows:

2551

#

2552

# Expression = Component { "." Component } { "/" Component } ;

2553

#

2554

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2564

# equivalent to `1` if it is used alone. For examples,

2565

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2566

# * `NAME` is a sequence of non-blank printable ASCII characters not

2567

# containing '{' or '}'.

2568

"name": "A String", # Resource name. The format of the name may vary between different

2569

# implementations. For examples:

2570

#

2571

# projects/{project_id}/metricDescriptors/{type=**}

2572

# metricDescriptors/{type=**}

2573

},

2574

],

2575

"enums": [ # A list of all enum types included in this API service. Enums

2576

# referenced directly or indirectly by the `apis` are automatically

2577

# included. Enums which are not referenced but shall be included

2578

# should be listed here by name. Example:

2579

#

2580

# enums:

2581

# - name: google.someapi.v1.SomeEnum

2582

{ # Enum type definition.

2583

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2584

# protobuf element, like the file in which it is defined.

2585

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2586

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2587

},

2588

"enumvalue": [ # Enum value definitions.

2589

{ # Enum value definition.

2590

"number": 42, # Enum value number.

2591

"options": [ # Protocol buffer options.

2592

{ # A protocol buffer option, which can be attached to a message, field,

2593

# enumeration, etc.

2594

"name": "A String", # The option's name. For example, `"java_package"`.

2595

"value": { # The option's value. For example, `"com.google.protobuf"`.

2596

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

2601

},

2602

],

2603

"options": [ # Protocol buffer options.

2604

{ # A protocol buffer option, which can be attached to a message, field,

2605

# enumeration, etc.

2606

"name": "A String", # The option's name. For example, `"java_package"`.

2607

"value": { # The option's value. For example, `"com.google.protobuf"`.

2608

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2613

"syntax": "A String", # The source syntax.

2614

},

2615

],

2616

"types": [ # A list of all proto message types included in this API service.

2617

# Types referenced directly or indirectly by the `apis` are

2618

# automatically included. Messages which are not referenced but

2619

# shall be included, such as types used by the `google.protobuf.Any` type,

2620

# should be listed here by name. Example:

2621

#

2622

# types:

2623

# - name: google.protobuf.Int32

2624

{ # A protocol buffer message type.

2625

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2626

"A String",

2627

],

2628

"name": "A String", # The fully qualified message name.

2629

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2630

# protobuf element, like the file in which it is defined.

2631

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2632

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2633

},

2634

"syntax": "A String", # The source syntax.

2635

"fields": [ # The list of fields.

2636

{ # A single field of a message type.

2637

"kind": "A String", # The field type.

2638

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2639

# types. The first type has index 1; zero means the type is not in the list.

2640

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2641

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2642

"name": "A String", # The field name.

2643

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2644

"jsonName": "A String", # The field JSON name.

2645

"number": 42, # The field number.

2646

"cardinality": "A String", # The field cardinality.

2647

"options": [ # The protocol buffer options.

2648

{ # A protocol buffer option, which can be attached to a message, field,

2649

# enumeration, etc.

2650

"name": "A String", # The option's name. For example, `"java_package"`.

2651

"value": { # The option's value. For example, `"com.google.protobuf"`.

2652

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2657

},

2658

],

2659

"options": [ # The protocol buffer options.

2660

{ # A protocol buffer option, which can be attached to a message, field,

2661

# enumeration, etc.

2662

"name": "A String", # The option's name. For example, `"java_package"`.

2663

"value": { # The option's value. For example, `"com.google.protobuf"`.

2664

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2670

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2671

#

2672

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2673

# producer and consumer projects. In the example, the `activity_history`

2674

# log is sent to both the producer and consumer projects, whereas the

2675

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2676

#

2677

# monitored_resources:

2678

# - type: library.googleapis.com/branch

2679

# labels:

2680

# - key: /city

2681

# description: The city where the library branch is located in.

2682

# - key: /name

2683

# description: The name of the branch.

2684

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2685

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2686

# labels:

2687

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2688

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2689

# logging:

2690

# producer_destinations:

2691

# - monitored_resource: library.googleapis.com/branch

2692

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2693

# - activity_history

2694

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2695

# consumer_destinations:

2696

# - monitored_resource: library.googleapis.com/branch

2697

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2698

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2699

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2700

# There can be multiple producer destinations, each one must have a

2701

# different monitored resource type. A log can be used in at most

2702

# one producer destination.

2703

{ # Configuration of a specific logging destination (the producer project

2704

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2705

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2706

# Service.monitored_resources section.

2707

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2708

# be defined in the Service.logs section. If the log name is

2709

# not a domain scoped name, it will be automatically prefixed with

2710

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

2716

# There can be multiple consumer destinations, each one must have a

2717

# different monitored resource type. A log can be used in at most

2718

# one consumer destination.

2719

{ # Configuration of a specific logging destination (the producer project

2720

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2721

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2722

# Service.monitored_resources section.

2723

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

2724

# be defined in the Service.logs section. If the log name is

2725

# not a domain scoped name, it will be automatically prefixed with

2726

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

2733

# e.g. `calendar.googleapis.com`.

2734

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2735

#

2736

# Example:

2737

# <pre><code>documentation:

2738

# summary: >

2739

# The Google Calendar API gives access

2740

# to most calendar features.

2741

# pages:

2742

# - name: Overview

2743

# content: (== include google/foo/overview.md ==)

2744

# - name: Tutorial

2745

# content: (== include google/foo/tutorial.md ==)

2746

# subpages;

2747

# - name: Java

2748

# content: (== include google/foo/tutorial_java.md ==)

2749

# rules:

2750

# - selector: google.calendar.Calendar.Get

2751

# description: >

2752

# ...

2753

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2758

# standard markdown features, definition lists, tables and fenced

2759

# code blocks are supported. Section headers can be provided and are

2760

# interpreted relative to the section nesting of the context where

2761

# a documentation fragment is embedded.

2762

#

2763

# Documentation from the IDL is merged with documentation defined

2764

# via the config at normalization time, where documentation provided

2765

# by config rules overrides IDL provided.

2766

#

2767

# A number of constructs specific to the API platform are supported

2768

# in documentation text.

2769

#

2770

# In order to reference a proto element, the following

2771

# notation can be used:

2772

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2773

# To override the display text used for the link, this can be used:

2774

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2775

# Text can be excluded from doc using the following notation:

2776

# <pre><code>(-- internal comment --)</code></pre>

2777

# Comments can be made conditional using a visibility label. The below

2778

# text will be only rendered if the `BETA` label is available:

2779

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2780

# A few directives are available in documentation. Note that

2781

# directives must appear on a single line to be properly

2782

# identified. The `include` directive includes a markdown file from

2783

# an external source:

2784

# <pre><code>(== include path/to/file ==)</code></pre>

2785

# The `resource_for` directive marks a message to be the resource of

2786

# a collection in REST view. If it is not specified, tools attempt

2787

# to infer the resource from the operations in a collection:

2788

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2789

# The directive `suppress_warning` does not directly affect documentation

2790

# and is documented together with service config validation.

2791

"rules": [ # A list of documentation rules that apply to individual API elements.

2792

#

2793

# **NOTE:** All service configuration rules follow "last one wins" order.

2794

{ # A documentation rule provides information about individual API elements.

2795

"description": "A String", # Description of the selected API(s).

2796

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2797

# element is marked as `deprecated`.

2798

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2799

# qualified name of the element which may end in "*", indicating a wildcard.

2800

# Wildcards are only allowed at the end and for a whole component of the

2801

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2802

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

2807

# <pre><code>documentation:

2808

# summary: ...

2809

# overview: (== include overview.md ==)

2810

# </code></pre>

2811

# This is a shortcut for the following declaration (using pages style):

2812

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2817

# </code></pre>

2818

# Note: you cannot specify both `overview` field and `pages` field.

2819

"summary": "A String", # A short summary of what the service does. Can only be provided by

2820

# plain text.

2821

"pages": [ # The top level pages for the documentation set.

2822

{ # Represents a documentation page. A page can contain subpages to represent

2823

# nested documentation set structure.

2824

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2825

# to include content from a Markdown file.

2826

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2827

# honored in the generated docset.

2828

# Object with schema name: Page

2829

],

2830

"name": "A String", # The name of the page. It will be used as an identity of the page to

2831

# generate URI of the page, text of the link to this page in navigation,

2832

# etc. The full page name (start from the root page name to this page

2833

# concatenated with `.`) can be used as reference to the page in your

2834

# documentation. For example:

2835

# <pre><code>pages:

2836

# - name: Tutorial

2837

# content: (== include tutorial.md ==)

2838

# subpages:

2839

# - name: Java

2840

# content: (== include tutorial_java.md ==)

2841

# </code></pre>

2842

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

2847

},

2848

"systemTypes": [ # A list of all proto message types included in this API service.

2849

# It serves similar purpose as [google.api.Service.types], except that

2850

# these types are not needed by user-defined APIs. Therefore, they will not

2851

# show up in the generated discovery doc. This field should only be used

2852

# to define system APIs in ESF.

2853

{ # A protocol buffer message type.

2854

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2855

"A String",

2856

],

2857

"name": "A String", # The fully qualified message name.

2858

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2859

# protobuf element, like the file in which it is defined.

2860

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2861

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2862

},

2863

"syntax": "A String", # The source syntax.

2864

"fields": [ # The list of fields.

2865

{ # A single field of a message type.

2866

"kind": "A String", # The field type.

2867

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2868

# types. The first type has index 1; zero means the type is not in the list.

2869

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2870

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2871

"name": "A String", # The field name.

2872

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2873

"jsonName": "A String", # The field JSON name.

2874

"number": 42, # The field number.

2875

"cardinality": "A String", # The field cardinality.

2876

"options": [ # The protocol buffer options.

2877

{ # A protocol buffer option, which can be attached to a message, field,

2878

# enumeration, etc.

2879

"name": "A String", # The option's name. For example, `"java_package"`.

2880

"value": { # The option's value. For example, `"com.google.protobuf"`.

2881

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2886

},

2887

],

2888

"options": [ # The protocol buffer options.

2889

{ # A protocol buffer option, which can be attached to a message, field,

2890

# enumeration, etc.

2891

"name": "A String", # The option's name. For example, `"java_package"`.

2892

"value": { # The option's value. For example, `"com.google.protobuf"`.

2893

"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

2908

# - google.rpc.context.OriginContext

2909

#

2910

# The above specifies that all methods in the API request

2911

# `google.rpc.context.ProjectContext` and

2912

# `google.rpc.context.OriginContext`.

2913

#

2914

# Available context types are defined in package

2915

# `google.rpc.context`.

2916

"rules": [ # A list of RPC context rules that apply to individual API methods.

2917

#

2918

# **NOTE:** All service configuration rules follow "last one wins" order.

2919

{ # A context rule provides information about the context for an individual API

2920

# element.

2921

"provided": [ # A list of full type names of provided contexts.

2922

"A String",

2923

],

2924

"requested": [ # A list of full type names of requested contexts.

2925

"A String",

2926

],

2927

"selector": "A String", # Selects the methods to which this rule applies.

2928

#

2929

# Refer to selector for syntax details.

2930

},

2931

],

2932

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2933

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2934

# with the same name as the service is automatically generated to service all

2935

# defined APIs.

2936

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2937

# A service may expose any number of endpoints, and all endpoints share the

2938

# same service configuration, such as quota configuration and monitoring

2939

# configuration.

2940

#

2941

# Example service configuration:

2942

#

2943

# name: library-example.googleapis.com

2944

# endpoints:

2945

# # Below entry makes 'google.example.library.v1.Library'

2946

# # API be served from endpoint address library-example.googleapis.com.

2947

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2948

# # it to decide whether the subsequent cross-origin request is

2949

# # allowed to proceed.

2950

# - name: library-example.googleapis.com

2951

# apis: google.example.library.v1.Library

2952

# allow_cors: true

2953

# # Below entry makes 'google.example.library.v1.Library'

2954

# # API be served from endpoint address

2955

# # google.example.library-example.v1.LibraryManager.

2956

# - name: library-manager.googleapis.com

2957

# apis: google.example.library.v1.LibraryManager

2958

# # BNS address for a borg job. Can specify a task by appending

2959

# # "/taskId" (e.g. "/0") to the job spec.

2960

#

2961

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

2967

# },

2968

# "host": "MY_PROJECT_ID.appspot.com",

2969

# "x-google-endpoints": [{

2970

# "name": "MY_PROJECT_ID.appspot.com",

2971

# "allow_cors": "true"

2972

# }]

2973

# }

2974

"allowCors": True or False, # Allowing

2975

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2976

# cross-domain traffic, would allow the backends served from this endpoint to

2977

# receive and respond to HTTP OPTIONS requests. The response will be used by

2978

# the browser to determine whether the subsequent cross-origin request is

2979

# allowed to proceed.

2980

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2981

# please specify multiple google.api.Endpoint for each of the intented

2982

# alias.

2983

#

2984

# Additional names that this endpoint will be hosted on.

2985

"A String",

2986

],

2987

"features": [ # The list of features enabled on this endpoint.

2988

"A String",

2989

],

2990

"name": "A String", # The canonical name of this endpoint.

2991

"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>

3001

<pre>Gets a service configuration (version) for a managed service.

3002

3003

Args:

3004

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3005

for naming requirements. For example: `example.googleapis.com`. (required)

3006

configId: string, A parameter (required)

3007

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3014

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3015

{ # `Service` is the root object of Google service configuration schema. It

3016

# describes basic information about a service, such as the name and the

3017

# title, and delegates other aspects to sub-sections. Each sub-section is

3018

# either a proto message or a repeated proto message that configures a

3019

# 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]

3024

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3025

# name: calendar.googleapis.com

3026

# title: Google Calendar API

3027

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3028

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3029

# backend:

3030

# rules:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3031

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3032

# address: calendar.example.com

3033

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3034

# service controller handles features like abuse, quota, billing, logging,

3035

# monitoring, etc.

3036

"environment": "A String", # The service control environment to use. If empty, no control plane

3037

# feature (like quota and billing) will be enabled.

3038

},

3039

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3040

# by the Service.monitoring and Service.logging configurations.

3041

{ # An object that describes the schema of a MonitoredResource object using a

3042

# type name and a set of labels. For example, the monitored resource

3043

# descriptor for Google Compute Engine VM instances has a type of

3044

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3045

# `"zone"` to identify particular VM instances.

3046

#

3047

# Different APIs can support different monitored resource types. APIs generally

3048

# provide a `list` method that returns the monitored resource descriptors used

3049

# by the API.

3050

"type": "A String", # Required. The monitored resource type. For example, the type

3051

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3052

# The maximum length of this value is 256 characters.

3053

"labels": [ # Required. A set of labels used to describe instances of this monitored

3054

# resource type. For example, an individual Google Cloud SQL database is

3055

# identified by values for the labels `"database_id"` and `"zone"`.

3056

{ # A description of a label.

3057

"valueType": "A String", # The type of data that can be assigned to the label.

3058

"description": "A String", # A human-readable description for the label.

3059

"key": "A String", # The label key.

3060

},

3061

],

3062

"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]

3063

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3064

# without any article or other determiners. For example,

3065

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3066

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3067

# be used in documentation.

3068

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3069

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3070

# {type} is the value of the `type` field in this object and

3071

# {project_id} is a project ID that provides API-specific context for

3072

# accessing the type. APIs that do not use project information can use the

3073

# resource name format `"monitoredResourceDescriptors/{type}"`.

3074

},

3075

],

3076

"logs": [ # Defines the logs used by this service.

3077

{ # A description of a log type. Example in YAML format:

3078

#

3079

# - name: library.googleapis.com/activity_history

3080

# description: The history of borrowing and returning library items.

3081

# display_name: Activity

3082

# labels:

3083

# - key: /customer_id

3084

# description: Identifier of a library customer

3085

"labels": [ # The set of labels that are available to describe a specific log entry.

3086

# Runtime requests that contain labels not specified here are

3087

# considered invalid.

3088

{ # A description of a label.

3089

"valueType": "A String", # The type of data that can be assigned to the label.

3090

"description": "A String", # A human-readable description for the label.

3091

"key": "A String", # The label key.

3092

},

3093

],

3094

"displayName": "A String", # The human-readable name for this log. This information appears on

3095

# the user interface and should be concise.

3096

"description": "A String", # A human-readable description of this log. This information appears in

3097

# the documentation and can contain details.

3098

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3099

# include the following characters: upper- and lower-case alphanumeric

3100

# characters [A-Za-z0-9], and punctuation characters including

3101

# slash, underscore, hyphen, period [/_-.].

3102

},

3103

],

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

3104

"analytics": { # Analytics configuration of the service. # WARNING: DO NOT USE UNTIL THIS MESSAGE IS REMOVED.

3105

#

3106

# Analytics configuration.

3107

#

3108

# The example below shows how to configure monitored resources and metrics

3109

# for analytics. In the example, a monitored resource and two metrics are

3110

# defined. The `library.googleapis.com/book/returned_count` and

3111

# `library.googleapis.com/book/overdue_count` metric are sent

3112

# to the analytics.

3113

#

3114

# monitored_resources:

3115

# - type: library.googleapis.com/branch

3116

# labels:

3117

# - key: /city

3118

# description: The city where the library branch is located in.

3119

# - key: /name

3120

# description: The name of the branch.

3121

# metrics:

3122

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3127

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3132

# analytics:

3133

# producer_destinations:

3134

# - monitored_resource: library.googleapis.com/branch

3135

# metrics:

3136

# - library.googleapis.com/book/returned_count

3137

# - library.googleapis.com/book/overdue_count

3138

"producerDestinations": [ # Analytics configurations for sending metrics to the analytics backend.

3139

# There can be multiple producer destinations, each one must have a

3140

# different monitored resource type. A metric can be used in at most

3141

# one producer destination.

3142

{ # Configuration of a specific analytics destination.

3143

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3144

# Service.monitored_resources section.

3145

"metrics": [ # Names of the metrics to report to this analytics destination.

3146

# Each name must be defined in Service.metrics section. Metrics

3147

# with value type BOOL and STRING must be of GUAGE kind, metrics with

3148

# value type INT64, DOUBLE and MONEY must be of DELTA kind.

"A String",

],

},

],

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3154

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3155

#

3156

# A system parameter is a special kind of parameter defined by the API

3157

# system, not by an individual API. It is typically mapped to an HTTP header

3158

# and/or a URL query parameter. This configuration specifies which methods

3159

# change the names of the system parameters.

3160

"rules": [ # Define system parameters.

3161

#

3162

# The parameters defined here will override the default parameters

3163

# implemented by the system. If this field is missing from the service

3164

# config, default system parameters will be used. Default system parameters

3165

# and names is implementation-dependent.

3166

#

3167

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3175

# - name: alt

3176

# http_header: Response-Content-Type

3177

#

3178

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

3183

# parameters:

3184

# - name: api_key

3185

# http_header: Api-Key1

3186

# - name: api_key

3187

# http_header: Api-Key2

3188

#

3189

# **NOTE:** All service configuration rules follow "last one wins" order.

3190

{ # Define a system parameter rule mapping system parameter definitions to

3191

# methods.

3192

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3193

# For a given method call, only one of them should be used. If multiple

3194

# names are used the behavior is implementation-dependent.

3195

# If none of the specified names are present the behavior is

3196

# parameter-dependent.

3197

{ # Define a parameter's name and location. The parameter may be passed as either

3198

# an HTTP header or a URL query parameter, and if both are passed the behavior

3199

# is implementation-dependent.

3200

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3201

# sensitive.

3202

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

3203

# and etc. It is case sensitive.

3204

"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

3209

# methods in all APIs.

3210

#

3211

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3216

"rules": [ # A list of API backend rules that apply to individual API methods.

3217

#

3218

# **NOTE:** All service configuration rules follow "last one wins" order.

3219

{ # A backend rule provides configuration for an individual API element.

3220

"selector": "A String", # Selects the methods to which this rule applies.

3221

#

3222

# Refer to selector for syntax details.

3223

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

3224

# default depends on the deployment context.

3225

"address": "A String", # The address of the API backend.

3226

},

3227

],

3228

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3229

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3230

#

3231

# The example below shows how to configure monitored resources and metrics

3232

# for monitoring. In the example, a monitored resource and two metrics are

3233

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3234

# to both producer and consumer projects, whereas the

3235

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3236

# consumer project.

3237

#

3238

# monitored_resources:

3239

# - type: library.googleapis.com/branch

3240

# labels:

3241

# - key: /city

3242

# description: The city where the library branch is located in.

3243

# - key: /name

3244

# description: The name of the branch.

3245

# metrics:

3246

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3251

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3256

# monitoring:

3257

# producer_destinations:

3258

# - monitored_resource: library.googleapis.com/branch

3259

# metrics:

3260

# - library.googleapis.com/book/returned_count

3261

# consumer_destinations:

3262

# - monitored_resource: library.googleapis.com/branch

3263

# metrics:

3264

# - library.googleapis.com/book/returned_count

3265

# - library.googleapis.com/book/overdue_count

3266

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3267

# There can be multiple producer destinations, each one must have a

3268

# different monitored resource type. A metric can be used in at most

3269

# one producer destination.

3270

{ # Configuration of a specific monitoring destination (the producer project

3271

# or the consumer project).

3272

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3273

# Service.monitored_resources section.

3274

"metrics": [ # Names of the metrics to report to this monitoring destination.

3275

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3281

# There can be multiple consumer destinations, each one must have a

3282

# different monitored resource type. A metric can be used in at most

3283

# one consumer destination.

3284

{ # Configuration of a specific monitoring destination (the producer project

3285

# or the consumer project).

3286

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3287

# Service.monitored_resources section.

3288

"metrics": [ # Names of the metrics to report to this monitoring destination.

3289

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

3296

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3297

# by the client for tracking purpose. If empty, the server may choose to

3298

# generate one instead.

3299

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3300

#

3301

# Example for an API targeted for external use:

3302

#

3303

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

3309

#

3310

# - selector: google.calendar.Delegate

3311

# oauth:

3312

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

3313

"rules": [ # A list of authentication rules that apply to individual API methods.

3314

#

3315

# **NOTE:** All service configuration rules follow "last one wins" order.

3316

{ # Authentication rules for the service.

3317

#

3318

# By default, if a method has any authentication requirements, every request

3319

# must include a valid credential matching one of the requirements.

3320

# It's an error to include more than one kind of credential in a single

3321

# request.

3322

#

3323

# If a method doesn't have any auth requirements, request credentials will be

3324

# ignored.

3325

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3326

# there are scopes defined for "Read-only access to Google Calendar" and

3327

# "Access to Cloud Platform". Users can consent to a scope for an application,

3328

# giving it permission to access that data on their behalf.

3329

#

3330

# OAuth scope specifications should be fairly coarse grained; a user will need

3331

# to see and understand the text description of what your scope means.

3332

#

3333

# In most cases: use one or at most two OAuth scopes for an entire family of

3334

# products. If your product has multiple APIs, you should probably be sharing

3335

# the OAuth scope across all of those APIs.

3336

#

3337

# When you need finer grained OAuth consent screens: talk with your product

3338

# management about how developers will use them in practice.

3339

#

3340

# Please note that even though each of the canonical scopes is enough for a

3341

# request to be accepted and passed to the backend, a request can still fail

3342

# due to the backend requiring additional scopes or permissions.

3343

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3344

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3349

# https://www.googleapis.com/auth/calendar.read

3350

},

3351

"requirements": [ # Requirements for additional authentication providers.

3352

{ # User-defined authentication requirements, including support for

3353

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3354

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

3359

"audiences": "A String", # The list of JWT

3360

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3361

# that are allowed to access. A JWT containing any of these audiences will

3362

# be accepted. When this setting is absent, only JWTs with audience

3363

# "https://Service_name/API_name"

3364

# will be accepted. For example, if no audiences are in the setting,

3365

# LibraryService API will only accept JWTs with the following audience

3366

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3371

# bookstore_web.apps.googleusercontent.com

3372

},

3373

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

3374

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3375

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3376

#

3377

# For requests without credentials, if the service control environment is

3378

# specified, each incoming request **must** be associated with a service

3379

# consumer. This can be done by passing an API key that belongs to a consumer

3380

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3381

"selector": "A String", # Selects the methods to which this rule applies.

3382

#

3383

# Refer to selector for syntax details.

3384

},

3385

],

3386

"providers": [ # Defines a set of authentication providers that a service supports.

3387

{ # Configuration for an anthentication provider, including support for

3388

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3389

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3390

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3391

# Optional if the key set document:

3392

# - can be retrieved from

3393

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3394

# of the issuer.

3395

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3396

#

3397

# Example: https://www.googleapis.com/oauth2/v1/certs

3398

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3399

# `AuthRequirement.provider_id`.

3400

#

3401

# Example: "bookstore_auth".

3402

"issuer": "A String", # Identifies the principal that issued the JWT. See

3403

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3404

# Usually a URL or an email address.

3405

#

3406

# Example: https://securetoken.google.com

3407

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3412

"rules": [ # A list of usage rules that apply to individual API methods.

3413

#

3414

# **NOTE:** All service configuration rules follow "last one wins" order.

3415

{ # Usage configuration rules for the service.

3416

#

3417

# NOTE: Under development.

3418

#

3419

#

3420

# Use this rule to configure unregistered calls for the service. Unregistered

3421

# calls are calls that do not contain consumer project identity.

3422

# (Example: calls that do not contain an API key).

3423

# By default, API methods do not allow unregistered calls, and each method call

3424

# must be identified by a consumer project identity. Use this rule to

3425

# allow/disallow unregistered calls.

3426

#

3427

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3433

#

3434

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3439

# allow_unregistered_calls: true

3440

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3441

# methods in all APIs.

3442

#

3443

# Refer to selector for syntax details.

3444

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3445

},

3446

],

3447

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3448

# service. Each requirement is of the form <service.name>/<requirement-id>;

3449

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3454

# influence interpretation of the configuration, for example, to

3455

# determine defaults. This is documented together with applicable

3456

# options. The current default for the config version itself is `3`.

3457

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3458

# Members of this project can manage the service configuration,

3459

# manage consumption of the service, etc.

3460

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3461

# HttpRule, each specifying the mapping of an RPC method

3462

# to one or more HTTP REST API methods.

3463

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3464

#

3465

# **NOTE:** All service configuration rules follow "last one wins" order.

3466

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3467

# REST APIs. The mapping determines what portions of the request

3468

# message are populated from the path, query parameters, or body of

3469

# the HTTP request. The mapping is typically specified as an

3470

# `google.api.http` annotation, see "google/api/annotations.proto"

3471

# for details.

3472

#

3473

# The mapping consists of a field specifying the path template and

3474

# method kind. The path template can refer to fields in the request

3475

# message, as in the example below which describes a REST GET

3476

# operation on a resource collection of messages:

3477

#

3478

# ```proto

3479

# service Messaging {

3480

# rpc GetMessage(GetMessageRequest) returns (Message) {

3481

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3482

# }

3483

# }

3484

# message GetMessageRequest {

3485

# message SubMessage {

3486

# string subfield = 1;

3487

# }

3488

# string message_id = 1; // mapped to the URL

3489

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3490

# }

3491

# message Message {

3492

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

3497

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3502

#

3503

# In general, not only fields but also field paths can be referenced

3504

# from a path pattern. Fields mapped to the path pattern cannot be

3505

# repeated and must have a primitive (non-message) type.

3506

#

3507

# Any fields in the request message which are not bound by the path

3508

# pattern automatically become (optional) HTTP query

3509

# parameters. Assume the following definition of the request message:

3510

#

3511

# ```proto

3512

# message GetMessageRequest {

3513

# message SubMessage {

3514

# string subfield = 1;

3515

# }

3516

# string message_id = 1; // mapped to the URL

3517

# int64 revision = 2; // becomes a parameter

3518

# 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"))`

3527

#

3528

# Note that fields which are mapped to HTTP parameters must have a

3529

# primitive type or a repeated primitive type. Message types are not

3530

# allowed. In the case of a repeated type, the parameter can be

3531

# repeated in the URL, as in `...?param=A&param=B`.

3532

#

3533

# For HTTP method kinds which allow a request body, the `body` field

3534

# specifies the mapping. Consider a REST update method on the

3535

# message resource collection:

3536

#

3537

# ```proto

3538

# service Messaging {

3539

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3540

# option (google.api.http) = {

3541

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3547

# string message_id = 1; // mapped to the URL

3548

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

3553

# representation of the JSON in the request body is determined by

3554

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3559

#

3560

# The special name `*` can be used in the body mapping to define that

3561

# every field not bound by the path template should be mapped to the

3562

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

3567

# rpc UpdateMessage(Message) returns (Message) {

3568

# option (google.api.http) = {

3569

# 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!")`

3585

#

3586

# Note that when using `*` in the body mapping, it is not possible to

3587

# have HTTP parameters, as all fields not bound by the path end in

3588

# the body. This makes this option more rarely used in practice of

3589

# defining REST APIs. The common usage of `*` is in custom methods

3590

# which don't use the URL at all for transferring data.

3591

#

3592

# It is possible to define multiple HTTP methods for one RPC by using

3593

# the `additional_bindings` option. Example:

3594

#

3595

# ```proto

3596

# service Messaging {

3597

# rpc GetMessage(GetMessageRequest) returns (Message) {

3598

# option (google.api.http) = {

3599

# get: "/v1/messages/{message_id}"

3600

# additional_bindings {

3601

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

3607

# string message_id = 1;

3608

# 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")`

3618

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

3619

#

3620

# # Rules for HTTP mapping

3621

#

3622

# The rules for mapping HTTP path, query parameters, and body fields

3623

# to the request message are as follows:

3624

#

3625

# 1. The `body` field specifies either `*` or a field path, or is

3626

# omitted. If omitted, it assumes there is no HTTP body.

3627

# 2. Leaf fields (recursive expansion of nested messages in the

3628

# request) can be classified into three types:

3629

# (a) Matched in the URL template.

3630

# (b) Covered by body (if body is `*`, everything except (a) fields;

3631

# else everything under the body field)

3632

# (c) All other fields.

3633

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

3634

# 4. Any body sent with an HTTP request can contain only (b) fields.

3635

#

3636

# The syntax of the path template is as follows:

3637

#

3638

# Template = "/" Segments [ Verb ] ;

3639

# Segments = Segment { "/" Segment } ;

3640

# Segment = "*" | "**" | LITERAL | Variable ;

3641

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

3642

# FieldPath = IDENT { "." IDENT } ;

3643

# Verb = ":" LITERAL ;

3644

#

3645

# The syntax `*` matches a single path segment. It follows the semantics of

3646

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

3647

# Expansion.

3648

#

3649

# The syntax `**` matches zero or more path segments. It follows the semantics

3650

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

3651

# Expansion.

3652

#

3653

# The syntax `LITERAL` matches literal text in the URL path.

3654

#

3655

# The syntax `Variable` matches the entire path as specified by its template;

3656

# this nested template must not contain further variables. If a variable

3657

# matches a single path segment, its template may be omitted, e.g. `{var}`

3658

# is equivalent to `{var=*}`.

3659

#

3660

# NOTE: the field paths in variables and in the `body` must not refer to

3661

# repeated fields or map fields.

3662

#

3663

# Use CustomHttpPattern to specify any HTTP method that is not included in the

3664

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

3665

# a given URL path rule. The wild-card rule is useful for services that provide

3666

# content to Web (HTML) clients.

3667

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

3668

# `*` for mapping all fields not captured by the path pattern to the HTTP

3669

# body. NOTE: the referred field must not be a repeated field and must be

3670

# present at the top-level of response message type.

3671

"get": "A String", # Used for listing and getting information about resources.

3672

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3673

# [][google.bytestream.RestByteStream] as an API to your

3674

# configuration.

3675

# [][google.bytestream.RestByteStream] as an API to your

3676

# configuration.

3677

"enabled": True or False, # Whether download is enabled.

3678

},

3679

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

3680

# not contain an `additional_bindings` field themselves (that is,

3681

# the nesting may only be one level deep).

3682

# Object with schema name: HttpRule

3683

],

3684

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

3685

# [][google.bytestream.RestByteStream] as an API to your

3686

# configuration.

3687

# [][google.bytestream.RestByteStream] as an API to your

3688

# configuration.

3689

"enabled": True or False, # Whether upload is enabled.

3690

},

3691

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

3692

"path": "A String", # The path matched by this custom verb.

3693

"kind": "A String", # The name of this custom HTTP verb.

3694

},

3695

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

3696

# response. Other response fields are ignored. This field is optional. When

3697

# not set, the response message will be used as HTTP body of response.

3698

# NOTE: the referred field must be not a repeated field and must be present

3699

# at the top-level of response message type.

3700

"put": "A String", # Used for updating a resource.

3701

"patch": "A String", # Used for updating a resource.

3702

"post": "A String", # Used for creating a resource.

3703

"selector": "A String", # Selects methods to which this rule applies.

3704

#

3705

# Refer to selector for syntax details.

3706

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

3711

# of the google.protobuf.Api needs to be provided by the configuration

3712

# author, as the remaining fields will be derived from the IDL during the

3713

# normalization process. It is an error to specify an API interface here

3714

# which cannot be resolved against the associated IDL files.

3715

{ # Api is a light-weight descriptor for a protocol buffer service.

3716

"methods": [ # The methods of this api, in unspecified order.

3717

{ # Method represents a method of an api.

3718

"name": "A String", # The simple name of this method.

3719

"requestStreaming": True or False, # If true, the request is streamed.

3720

"responseTypeUrl": "A String", # The URL of the output message type.

3721

"requestTypeUrl": "A String", # A URL of the input message type.

3722

"responseStreaming": True or False, # If true, the response is streamed.

3723

"syntax": "A String", # The source syntax of this method.

3724

"options": [ # Any metadata attached to the method.

3725

{ # A protocol buffer option, which can be attached to a message, field,

3726

# enumeration, etc.

3727

"name": "A String", # The option's name. For example, `"java_package"`.

3728

"value": { # The option's value. For example, `"com.google.protobuf"`.

3729

"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

3736

# message.

3737

# protobuf element, like the file in which it is defined.

3738

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3739

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3740

},

3741

"mixins": [ # Included APIs. See Mixin.

3742

{ # Declares an API to be included in this API. The including API must

3743

# redeclare all the methods from the included API, but documentation

3744

# and options are inherited as follows:

3745

#

3746

# - If after comment and whitespace stripping, the documentation

3747

# string of the redeclared method is empty, it will be inherited

3748

# from the original method.

3749

#

3750

# - Each annotation belonging to the service config (http,

3751

# visibility) which is not set in the redeclared method will be

3752

# inherited.

3753

#

3754

# - If an http annotation is inherited, the path pattern will be

3755

# modified as follows. Any version prefix will be replaced by the

3756

# version of the including API plus the root path if specified.

3757

#

3758

# Example of a simple mixin:

3759

#

3760

# package google.acl.v1;

3761

# service AccessControl {

3762

# // Get the underlying ACL object.

3763

# rpc GetAcl(GetAclRequest) returns (Acl) {

3764

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3769

# service Storage {

3770

# // rpc GetAcl(GetAclRequest) returns (Acl);

3771

#

3772

# // Get a data record.

3773

# rpc GetData(GetDataRequest) returns (Data) {

3774

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3779

#

3780

# apis:

3781

# - name: google.storage.v2.Storage

3782

# mixins:

3783

# - name: google.acl.v1.AccessControl

3784

#

3785

# The mixin construct implies that all methods in `AccessControl` are

3786

# also declared with same name and request/response types in

3787

# `Storage`. A documentation generator or annotation processor will

3788

# see the effective `Storage.GetAcl` method after inherting

3789

# documentation and annotations as follows:

3790

#

3791

# service Storage {

3792

# // Get the underlying ACL object.

3793

# rpc GetAcl(GetAclRequest) returns (Acl) {

3794

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3800

#

3801

# If the `root` field in the mixin is specified, it should be a

3802

# relative path under which inherited HTTP paths are placed. Example:

3803

#

3804

# apis:

3805

# - name: google.storage.v2.Storage

3806

# mixins:

3807

# - name: google.acl.v1.AccessControl

3808

# root: acls

3809

#

3810

# This implies the following inherited HTTP annotation:

3811

#

3812

# service Storage {

3813

# // Get the underlying ACL object.

3814

# rpc GetAcl(GetAclRequest) returns (Acl) {

3815

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3820

# are rooted.

3821

"name": "A String", # The fully qualified name of the API which is included.

3822

},

3823

],

3824

"syntax": "A String", # The source syntax of the service.

3825

"version": "A String", # A version string for this api. If specified, must have the form

3826

# `major-version.minor-version`, as in `1.10`. If the minor version

3827

# is omitted, it defaults to zero. If the entire version field is

3828

# empty, the major version is derived from the package name, as

3829

# outlined below. If the field is not empty, the version in the

3830

# package name will be verified to be consistent with what is

3831

# provided here.

3832

#

3833

# The versioning schema uses [semantic

3834

# versioning](http://semver.org) where the major version number

3835

# indicates a breaking change and the minor version an additive,

3836

# non-breaking change. Both version numbers are signals to users

3837

# what to expect from different versions, and should be carefully

3838

# chosen based on the product plan.

3839

#

3840

# The major version is also reflected in the package name of the

3841

# API, which must end in `v<major-version>`, as in

3842

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3843

# be omitted. Zero major versions must only be used for

3844

# experimental, none-GA apis.

3845

"options": [ # Any metadata attached to the API.

3846

{ # A protocol buffer option, which can be attached to a message, field,

3847

# enumeration, etc.

3848

"name": "A String", # The option's name. For example, `"java_package"`.

3849

"value": { # The option's value. For example, `"com.google.protobuf"`.

3850

"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

3855

# followed by the api's simple name.

3856

},

3857

],

3858

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3859

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3867

# - google.foo.v1.AnotherError

3868

"rules": [ # The list of custom error rules that apply to individual API messages.

3869

#

3870

# **NOTE:** All service configuration rules follow "last one wins" order.

3871

{ # A custom error rule.

3872

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3873

# objects of this type will be filtered when they appear in error payload.

3874

"selector": "A String", # Selects messages to which this rule applies.

3875

#

3876

# Refer to selector for syntax details.

3877

},

3878

],

3879

"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.

3884

# elements. Restrictions are specified using visibility labels

3885

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3886

#

3887

# Users and projects can have access to more than one visibility label. The

3888

# effective visibility for multiple labels is the union of each label's

3889

# elements, plus any unrestricted elements.

3890

#

3891

# If an element and its parents have no restrictions, visibility is

3892

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3899

# restriction: TRUSTED_TESTER

3900

# - selector: google.calendar.Calendar.Delegate

3901

# restriction: GOOGLE_INTERNAL

3902

#

3903

# Here, all methods are publicly visible except for the restricted methods

3904

# EnhancedSearch and Delegate.

3905

"rules": [ # A list of visibility rules that apply to individual API elements.

3906

#

3907

# **NOTE:** All service configuration rules follow "last one wins" order.

3908

{ # A visibility rule provides visibility configuration for an individual API

3909

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3910

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

3911

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3912

#

3913

# If a rule has multiple labels, removing one of the labels but not all of

3914

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3921

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

3922

#

3923

# Removing GOOGLE_INTERNAL from this restriction will break clients that

3924

# rely on this method and only had access to it through GOOGLE_INTERNAL.

3925

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

3926

#

3927

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

3932

{ # Defines a metric type and its schema.

3933

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3934

# Use sentence case without an ending period, for example "Request count".

3935

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3936

"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]

3937

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3938

"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]

3939

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3940

"labels": [ # The set of labels that can be used to describe a specific instance of this

3941

# metric type. For example, the

3942

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

3943

# has a label, `loadbalanced`, that specifies whether the traffic was

3944

# received through a load balanced IP address.

3945

{ # A description of a label.

3946

"valueType": "A String", # The type of data that can be assigned to the label.

3947

"description": "A String", # A human-readable description for the label.

3948

"key": "A String", # The label key.

3949

},

3950

],

3951

"type": "A String", # The metric type including a DNS name prefix, for example

3952

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

3953

# should use a natural hierarchical grouping such as the following:

3954

#

3955

# compute.googleapis.com/instance/cpu/utilization

3956

# compute.googleapis.com/instance/disk/read_ops_count

3957

# compute.googleapis.com/instance/network/received_bytes_count

3958

#

3959

# Note that if the metric type changes, the monitoring data will be

3960

# discontinued, and anything depends on it will break, such as monitoring

3961

# dashboards, alerting rules and quota limits. Therefore, once a metric has

3962

# been published, its type should be immutable.

3963

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

3964

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

3965

# supported units are a subset of [The Unified Code for Units of

3966

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3967

#

3968

# **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)

3983

# * `P` peta (10**15)

3984

# * `E` exa (10**18)

3985

# * `Z` zetta (10**21)

3986

# * `Y` yotta (10**24)

3987

# * `m` milli (10**-3)

3988

# * `u` micro (10**-6)

3989

# * `n` nano (10**-9)

3990

# * `p` pico (10**-12)

3991

# * `f` femto (10**-15)

3992

# * `a` atto (10**-18)

3993

# * `z` zepto (10**-21)

3994

# * `y` yocto (10**-24)

3995

# * `Ki` kibi (2**10)

3996

# * `Mi` mebi (2**20)

3997

# * `Gi` gibi (2**30)

3998

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

4003

#

4004

# The grammar also includes these connectors:

4005

#

4006

# * `/` division (as an infix operator, e.g. `1/s`).

4007

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

4008

#

4009

# The grammar for a unit is as follows:

4010

#

4011

# Expression = Component { "." Component } { "/" Component } ;

4012

#

4013

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

4023

# equivalent to `1` if it is used alone. For examples,

4024

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

4025

# * `NAME` is a sequence of non-blank printable ASCII characters not

4026

# containing '{' or '}'.

4027

"name": "A String", # Resource name. The format of the name may vary between different

4028

# implementations. For examples:

4029

#

4030

# projects/{project_id}/metricDescriptors/{type=**}

4031

# metricDescriptors/{type=**}

4032

},

4033

],

4034

"enums": [ # A list of all enum types included in this API service. Enums

4035

# referenced directly or indirectly by the `apis` are automatically

4036

# included. Enums which are not referenced but shall be included

4037

# should be listed here by name. Example:

4038

#

4039

# enums:

4040

# - name: google.someapi.v1.SomeEnum

4041

{ # Enum type definition.

4042

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4043

# protobuf element, like the file in which it is defined.

4044

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4045

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4046

},

4047

"enumvalue": [ # Enum value definitions.

4048

{ # Enum value definition.

4049

"number": 42, # Enum value number.

4050

"options": [ # Protocol buffer options.

4051

{ # A protocol buffer option, which can be attached to a message, field,

4052

# enumeration, etc.

4053

"name": "A String", # The option's name. For example, `"java_package"`.

4054

"value": { # The option's value. For example, `"com.google.protobuf"`.

4055

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

4060

},

4061

],

4062

"options": [ # Protocol buffer options.

4063

{ # A protocol buffer option, which can be attached to a message, field,

4064

# enumeration, etc.

4065

"name": "A String", # The option's name. For example, `"java_package"`.

4066

"value": { # The option's value. For example, `"com.google.protobuf"`.

4067

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

4072

"syntax": "A String", # The source syntax.

4073

},

4074

],

4075

"types": [ # A list of all proto message types included in this API service.

4076

# Types referenced directly or indirectly by the `apis` are

4077

# automatically included. Messages which are not referenced but

4078

# shall be included, such as types used by the `google.protobuf.Any` type,

4079

# should be listed here by name. Example:

4080

#

4081

# types:

4082

# - name: google.protobuf.Int32

4083

{ # A protocol buffer message type.

4084

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4085

"A String",

4086

],

4087

"name": "A String", # The fully qualified message name.

4088

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4089

# protobuf element, like the file in which it is defined.

4090

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4091

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4092

},

4093

"syntax": "A String", # The source syntax.

4094

"fields": [ # The list of fields.

4095

{ # A single field of a message type.

4096

"kind": "A String", # The field type.

4097

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4098

# types. The first type has index 1; zero means the type is not in the list.

4099

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4100

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4101

"name": "A String", # The field name.

4102

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4103

"jsonName": "A String", # The field JSON name.

4104

"number": 42, # The field number.

4105

"cardinality": "A String", # The field cardinality.

4106

"options": [ # The protocol buffer options.

4107

{ # A protocol buffer option, which can be attached to a message, field,

4108

# enumeration, etc.

4109

"name": "A String", # The option's name. For example, `"java_package"`.

4110

"value": { # The option's value. For example, `"com.google.protobuf"`.

4111

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4116

},

4117

],

4118

"options": [ # The protocol buffer options.

4119

{ # A protocol buffer option, which can be attached to a message, field,

4120

# enumeration, etc.

4121

"name": "A String", # The option's name. For example, `"java_package"`.

4122

"value": { # The option's value. For example, `"com.google.protobuf"`.

4123

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4129

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4130

#

4131

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4132

# producer and consumer projects. In the example, the `activity_history`

4133

# log is sent to both the producer and consumer projects, whereas the

4134

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4135

#

4136

# monitored_resources:

4137

# - type: library.googleapis.com/branch

4138

# labels:

4139

# - key: /city

4140

# description: The city where the library branch is located in.

4141

# - key: /name

4142

# description: The name of the branch.

4143

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4144

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4145

# labels:

4146

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4147

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4148

# logging:

4149

# producer_destinations:

4150

# - monitored_resource: library.googleapis.com/branch

4151

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4152

# - activity_history

4153

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4154

# consumer_destinations:

4155

# - monitored_resource: library.googleapis.com/branch

4156

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4157

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4158

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4159

# There can be multiple producer destinations, each one must have a

4160

# different monitored resource type. A log can be used in at most

4161

# one producer destination.

4162

{ # Configuration of a specific logging destination (the producer project

4163

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4164

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4165

# Service.monitored_resources section.

4166

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4167

# be defined in the Service.logs section. If the log name is

4168

# not a domain scoped name, it will be automatically prefixed with

4169

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

4175

# There can be multiple consumer destinations, each one must have a

4176

# different monitored resource type. A log can be used in at most

4177

# one consumer destination.

4178

{ # Configuration of a specific logging destination (the producer project

4179

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4180

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4181

# Service.monitored_resources section.

4182

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4183

# be defined in the Service.logs section. If the log name is

4184

# not a domain scoped name, it will be automatically prefixed with

4185

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

4192

# e.g. `calendar.googleapis.com`.

4193

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4194

#

4195

# Example:

4196

# <pre><code>documentation:

4197

# summary: >

4198

# The Google Calendar API gives access

4199

# to most calendar features.

4200

# pages:

4201

# - name: Overview

4202

# content: (== include google/foo/overview.md ==)

4203

# - name: Tutorial

4204

# content: (== include google/foo/tutorial.md ==)

4205

# subpages;

4206

# - name: Java

4207

# content: (== include google/foo/tutorial_java.md ==)

4208

# rules:

4209

# - selector: google.calendar.Calendar.Get

4210

# description: >

4211

# ...

4212

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

4217

# standard markdown features, definition lists, tables and fenced

4218

# code blocks are supported. Section headers can be provided and are

4219

# interpreted relative to the section nesting of the context where

4220

# a documentation fragment is embedded.

4221

#

4222

# Documentation from the IDL is merged with documentation defined

4223

# via the config at normalization time, where documentation provided

4224

# by config rules overrides IDL provided.

4225

#

4226

# A number of constructs specific to the API platform are supported

4227

# in documentation text.

4228

#

4229

# In order to reference a proto element, the following

4230

# notation can be used:

4231

# <pre><code>[fully.qualified.proto.name][]</code></pre>

4232

# To override the display text used for the link, this can be used:

4233

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

4234

# Text can be excluded from doc using the following notation:

4235

# <pre><code>(-- internal comment --)</code></pre>

4236

# Comments can be made conditional using a visibility label. The below

4237

# text will be only rendered if the `BETA` label is available:

4238

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

4239

# A few directives are available in documentation. Note that

4240

# directives must appear on a single line to be properly

4241

# identified. The `include` directive includes a markdown file from

4242

# an external source:

4243

# <pre><code>(== include path/to/file ==)</code></pre>

4244

# The `resource_for` directive marks a message to be the resource of

4245

# a collection in REST view. If it is not specified, tools attempt

4246

# to infer the resource from the operations in a collection:

4247

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

4248

# The directive `suppress_warning` does not directly affect documentation

4249

# and is documented together with service config validation.

4250

"rules": [ # A list of documentation rules that apply to individual API elements.

4251

#

4252

# **NOTE:** All service configuration rules follow "last one wins" order.

4253

{ # A documentation rule provides information about individual API elements.

4254

"description": "A String", # Description of the selected API(s).

4255

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

4256

# element is marked as `deprecated`.

4257

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

4258

# qualified name of the element which may end in "*", indicating a wildcard.

4259

# Wildcards are only allowed at the end and for a whole component of the

4260

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

4261

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

4266

# <pre><code>documentation:

4267

# summary: ...

4268

# overview: (== include overview.md ==)

4269

# </code></pre>

4270

# This is a shortcut for the following declaration (using pages style):

4271

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

4276

# </code></pre>

4277

# Note: you cannot specify both `overview` field and `pages` field.

4278

"summary": "A String", # A short summary of what the service does. Can only be provided by

4279

# plain text.

4280

"pages": [ # The top level pages for the documentation set.

4281

{ # Represents a documentation page. A page can contain subpages to represent

4282

# nested documentation set structure.

4283

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

4284

# to include content from a Markdown file.

4285

"subpages": [ # Subpages of this page. The order of subpages specified here will be

4286

# honored in the generated docset.

4287

# Object with schema name: Page

4288

],

4289

"name": "A String", # The name of the page. It will be used as an identity of the page to

4290

# generate URI of the page, text of the link to this page in navigation,

4291

# etc. The full page name (start from the root page name to this page

4292

# concatenated with `.`) can be used as reference to the page in your

4293

# documentation. For example:

4294

# <pre><code>pages:

4295

# - name: Tutorial

4296

# content: (== include tutorial.md ==)

4297

# subpages:

4298

# - name: Java

4299

# content: (== include tutorial_java.md ==)

4300

# </code></pre>

4301

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

4306

},

4307

"systemTypes": [ # A list of all proto message types included in this API service.

4308

# It serves similar purpose as [google.api.Service.types], except that

4309

# these types are not needed by user-defined APIs. Therefore, they will not

4310

# show up in the generated discovery doc. This field should only be used

4311

# to define system APIs in ESF.

4312

{ # A protocol buffer message type.

4313

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4314

"A String",

4315

],

4316

"name": "A String", # The fully qualified message name.

4317

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4318

# protobuf element, like the file in which it is defined.

4319

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4320

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4321

},

4322

"syntax": "A String", # The source syntax.

4323

"fields": [ # The list of fields.

4324

{ # A single field of a message type.

4325

"kind": "A String", # The field type.

4326

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4327

# types. The first type has index 1; zero means the type is not in the list.

4328

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4329

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4330

"name": "A String", # The field name.

4331

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4332

"jsonName": "A String", # The field JSON name.

4333

"number": 42, # The field number.

4334

"cardinality": "A String", # The field cardinality.

4335

"options": [ # The protocol buffer options.

4336

{ # A protocol buffer option, which can be attached to a message, field,

4337

# enumeration, etc.

4338

"name": "A String", # The option's name. For example, `"java_package"`.

4339

"value": { # The option's value. For example, `"com.google.protobuf"`.

4340

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4345

},

4346

],

4347

"options": [ # The protocol buffer options.

4348

{ # A protocol buffer option, which can be attached to a message, field,

4349

# enumeration, etc.

4350

"name": "A String", # The option's name. For example, `"java_package"`.

4351

"value": { # The option's value. For example, `"com.google.protobuf"`.

4352

"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

4367

# - google.rpc.context.OriginContext

4368

#

4369

# The above specifies that all methods in the API request

4370

# `google.rpc.context.ProjectContext` and

4371

# `google.rpc.context.OriginContext`.

4372

#

4373

# Available context types are defined in package

4374

# `google.rpc.context`.

4375

"rules": [ # A list of RPC context rules that apply to individual API methods.

4376

#

4377

# **NOTE:** All service configuration rules follow "last one wins" order.

4378

{ # A context rule provides information about the context for an individual API

4379

# element.

4380

"provided": [ # A list of full type names of provided contexts.

4381

"A String",

4382

],

4383

"requested": [ # A list of full type names of requested contexts.

4384

"A String",

4385

],

4386

"selector": "A String", # Selects the methods to which this rule applies.

4387

#

4388

# Refer to selector for syntax details.

4389

},

4390

],

4391

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4392

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4393

# with the same name as the service is automatically generated to service all

4394

# defined APIs.

4395

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4396

# A service may expose any number of endpoints, and all endpoints share the

4397

# same service configuration, such as quota configuration and monitoring

4398

# configuration.

4399

#

4400

# Example service configuration:

4401

#

4402

# name: library-example.googleapis.com

4403

# endpoints:

4404

# # Below entry makes 'google.example.library.v1.Library'

4405

# # API be served from endpoint address library-example.googleapis.com.

4406

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4407

# # it to decide whether the subsequent cross-origin request is

4408

# # allowed to proceed.

4409

# - name: library-example.googleapis.com

4410

# apis: google.example.library.v1.Library

4411

# allow_cors: true

4412

# # Below entry makes 'google.example.library.v1.Library'

4413

# # API be served from endpoint address

4414

# # google.example.library-example.v1.LibraryManager.

4415

# - name: library-manager.googleapis.com

4416

# apis: google.example.library.v1.LibraryManager

4417

# # BNS address for a borg job. Can specify a task by appending

4418

# # "/taskId" (e.g. "/0") to the job spec.

4419

#

4420

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

4426

# },

4427

# "host": "MY_PROJECT_ID.appspot.com",

4428

# "x-google-endpoints": [{

4429

# "name": "MY_PROJECT_ID.appspot.com",

4430

# "allow_cors": "true"

4431

# }]

4432

# }

4433

"allowCors": True or False, # Allowing

4434

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4435

# cross-domain traffic, would allow the backends served from this endpoint to

4436

# receive and respond to HTTP OPTIONS requests. The response will be used by

4437

# the browser to determine whether the subsequent cross-origin request is

4438

# allowed to proceed.

4439

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4440

# please specify multiple google.api.Endpoint for each of the intented

4441

# alias.

4442

#

4443

# Additional names that this endpoint will be hosted on.

4444

"A String",

4445

],

4446

"features": [ # The list of features enabled on this endpoint.

4447

"A String",

4448

],

4449

"name": "A String", # The canonical name of this endpoint.

4450

"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>

4460

<pre>Lists the history of the service configuration for a managed service,

4461

from the newest to the oldest.

4462

4463

Args:

4464

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4465

for naming requirements. For example: `example.googleapis.com`. (required)

4466

pageSize: integer, The max number of items to include in the response list.

4467

pageToken: string, The token of the page to retrieve.

4468

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4475

4476

{ # Response message for ListServiceConfigs method.

4477

"nextPageToken": "A String", # The token of the next page of results.

4478

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4479

{ # `Service` is the root object of Google service configuration schema. It

4480

# describes basic information about a service, such as the name and the

4481

# title, and delegates other aspects to sub-sections. Each sub-section is

4482

# either a proto message or a repeated proto message that configures a

4483

# 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]

4488

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4489

# name: calendar.googleapis.com

4490

# title: Google Calendar API

4491

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4492

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4493

# backend:

4494

# rules:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4495

# - selector: "google.calendar.v3.*"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4496

# address: calendar.example.com

4497

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4498

# service controller handles features like abuse, quota, billing, logging,

4499

# monitoring, etc.

4500

"environment": "A String", # The service control environment to use. If empty, no control plane

4501

# feature (like quota and billing) will be enabled.

4502

},

4503

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4504

# by the Service.monitoring and Service.logging configurations.

4505

{ # An object that describes the schema of a MonitoredResource object using a

4506

# type name and a set of labels. For example, the monitored resource

4507

# descriptor for Google Compute Engine VM instances has a type of

4508

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4509

# `"zone"` to identify particular VM instances.

4510

#

4511

# Different APIs can support different monitored resource types. APIs generally

4512

# provide a `list` method that returns the monitored resource descriptors used

4513

# by the API.

4514

"type": "A String", # Required. The monitored resource type. For example, the type

4515

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4516

# The maximum length of this value is 256 characters.

4517

"labels": [ # Required. A set of labels used to describe instances of this monitored

4518

# resource type. For example, an individual Google Cloud SQL database is

4519

# identified by values for the labels `"database_id"` and `"zone"`.

4520

{ # A description of a label.

4521

"valueType": "A String", # The type of data that can be assigned to the label.

4522

"description": "A String", # A human-readable description for the label.

4523

"key": "A String", # The label key.

4524

},

4525

],

4526

"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]

4527

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

4528

# without any article or other determiners. For example,

4529

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4530

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4531

# be used in documentation.

4532

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4533

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4534

# {type} is the value of the `type` field in this object and

4535

# {project_id} is a project ID that provides API-specific context for

4536

# accessing the type. APIs that do not use project information can use the

4537

# resource name format `"monitoredResourceDescriptors/{type}"`.

4538

},

4539

],

4540

"logs": [ # Defines the logs used by this service.

4541

{ # A description of a log type. Example in YAML format:

4542

#

4543

# - name: library.googleapis.com/activity_history

4544

# description: The history of borrowing and returning library items.

4545

# display_name: Activity

4546

# labels:

4547

# - key: /customer_id

4548

# description: Identifier of a library customer

4549

"labels": [ # The set of labels that are available to describe a specific log entry.

4550

# Runtime requests that contain labels not specified here are

4551

# considered invalid.

4552

{ # A description of a label.

4553

"valueType": "A String", # The type of data that can be assigned to the label.

4554

"description": "A String", # A human-readable description for the label.

4555

"key": "A String", # The label key.

4556

},

4557

],

4558

"displayName": "A String", # The human-readable name for this log. This information appears on

4559

# the user interface and should be concise.

4560

"description": "A String", # A human-readable description of this log. This information appears in

4561

# the documentation and can contain details.

4562

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4563

# include the following characters: upper- and lower-case alphanumeric

4564

# characters [A-Za-z0-9], and punctuation characters including

4565

# slash, underscore, hyphen, period [/_-.].

4566

},

4567

],

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

4568

"analytics": { # Analytics configuration of the service. # WARNING: DO NOT USE UNTIL THIS MESSAGE IS REMOVED.

4569

#

4570

# Analytics configuration.

4571

#

4572

# The example below shows how to configure monitored resources and metrics

4573

# for analytics. In the example, a monitored resource and two metrics are

4574

# defined. The `library.googleapis.com/book/returned_count` and

4575

# `library.googleapis.com/book/overdue_count` metric are sent

4576

# to the analytics.

4577

#

4578

# monitored_resources:

4579

# - type: library.googleapis.com/branch

4580

# labels:

4581

# - key: /city

4582

# description: The city where the library branch is located in.

4583

# - key: /name

4584

# description: The name of the branch.

4585

# metrics:

4586

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4591

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4596

# analytics:

4597

# producer_destinations:

4598

# - monitored_resource: library.googleapis.com/branch

4599

# metrics:

4600

# - library.googleapis.com/book/returned_count

4601

# - library.googleapis.com/book/overdue_count

4602

"producerDestinations": [ # Analytics configurations for sending metrics to the analytics backend.

4603

# There can be multiple producer destinations, each one must have a

4604

# different monitored resource type. A metric can be used in at most

4605

# one producer destination.

4606

{ # Configuration of a specific analytics destination.

4607

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4608

# Service.monitored_resources section.

4609

"metrics": [ # Names of the metrics to report to this analytics destination.

4610

# Each name must be defined in Service.metrics section. Metrics

4611

# with value type BOOL and STRING must be of GUAGE kind, metrics with

4612

# value type INT64, DOUBLE and MONEY must be of DELTA kind.

"A String",

],

},

],

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4618

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4619

#

4620

# A system parameter is a special kind of parameter defined by the API

4621

# system, not by an individual API. It is typically mapped to an HTTP header

4622

# and/or a URL query parameter. This configuration specifies which methods

4623

# change the names of the system parameters.

4624

"rules": [ # Define system parameters.

4625

#

4626

# The parameters defined here will override the default parameters

4627

# implemented by the system. If this field is missing from the service

4628

# config, default system parameters will be used. Default system parameters

4629

# and names is implementation-dependent.

4630

#

4631

# Example: define api key and alt name for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4639

# - name: alt

4640

# http_header: Response-Content-Type

4641

#

4642

# Example: define 2 api key names for a specific method.

#

# system_parameters

# rules:

# - selector: "/ListShelves"

4647

# parameters:

4648

# - name: api_key

4649

# http_header: Api-Key1

4650

# - name: api_key

4651

# http_header: Api-Key2

4652

#

4653

# **NOTE:** All service configuration rules follow "last one wins" order.

4654

{ # Define a system parameter rule mapping system parameter definitions to

4655

# methods.

4656

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4657

# For a given method call, only one of them should be used. If multiple

4658

# names are used the behavior is implementation-dependent.

4659

# If none of the specified names are present the behavior is

4660

# parameter-dependent.

4661

{ # Define a parameter's name and location. The parameter may be passed as either

4662

# an HTTP header or a URL query parameter, and if both are passed the behavior

4663

# is implementation-dependent.

4664

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4665

# sensitive.

4666

"name": "A String", # Define the name of the parameter, such as "api_key", "alt", "callback",

4667

# and etc. It is case sensitive.

4668

"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

4673

# methods in all APIs.

4674

#

4675

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4680

"rules": [ # A list of API backend rules that apply to individual API methods.

4681

#

4682

# **NOTE:** All service configuration rules follow "last one wins" order.

4683

{ # A backend rule provides configuration for an individual API element.

4684

"selector": "A String", # Selects the methods to which this rule applies.

4685

#

4686

# Refer to selector for syntax details.

4687

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4688

# default depends on the deployment context.

4689

"address": "A String", # The address of the API backend.

4690

},

4691

],

4692

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4693

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4694

#

4695

# The example below shows how to configure monitored resources and metrics

4696

# for monitoring. In the example, a monitored resource and two metrics are

4697

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4698

# to both producer and consumer projects, whereas the

4699

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4700

# consumer project.

4701

#

4702

# monitored_resources:

4703

# - type: library.googleapis.com/branch

4704

# labels:

4705

# - key: /city

4706

# description: The city where the library branch is located in.

4707

# - key: /name

4708

# description: The name of the branch.

4709

# metrics:

4710

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4715

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4720

# monitoring:

4721

# producer_destinations:

4722

# - monitored_resource: library.googleapis.com/branch

4723

# metrics:

4724

# - library.googleapis.com/book/returned_count

4725

# consumer_destinations:

4726

# - monitored_resource: library.googleapis.com/branch

4727

# metrics:

4728

# - library.googleapis.com/book/returned_count

4729

# - library.googleapis.com/book/overdue_count

4730

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4731

# There can be multiple producer destinations, each one must have a

4732

# different monitored resource type. A metric can be used in at most

4733

# one producer destination.

4734

{ # Configuration of a specific monitoring destination (the producer project

4735

# or the consumer project).

4736

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4737

# Service.monitored_resources section.

4738

"metrics": [ # Names of the metrics to report to this monitoring destination.

4739

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4745

# There can be multiple consumer destinations, each one must have a

4746

# different monitored resource type. A metric can be used in at most

4747

# one consumer destination.

4748

{ # Configuration of a specific monitoring destination (the producer project

4749

# or the consumer project).

4750

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4751

# Service.monitored_resources section.

4752

"metrics": [ # Names of the metrics to report to this monitoring destination.

4753

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

4760

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4761

# by the client for tracking purpose. If empty, the server may choose to

4762

# generate one instead.

4763

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4764

#

4765

# Example for an API targeted for external use:

4766

#

4767

# name: calendar.googleapis.com

# authentication:

# rules:

# - selector: "*"

# oauth:

# canonical_scopes: https://www.googleapis.com/auth/calendar

4773

#

4774

# - selector: google.calendar.Delegate

4775

# oauth:

4776

# canonical_scopes: https://www.googleapis.com/auth/calendar.read

4777

"rules": [ # A list of authentication rules that apply to individual API methods.

4778

#

4779

# **NOTE:** All service configuration rules follow "last one wins" order.

4780

{ # Authentication rules for the service.

4781

#

4782

# By default, if a method has any authentication requirements, every request

4783

# must include a valid credential matching one of the requirements.

4784

# It's an error to include more than one kind of credential in a single

4785

# request.

4786

#

4787

# If a method doesn't have any auth requirements, request credentials will be

4788

# ignored.

4789

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4790

# there are scopes defined for "Read-only access to Google Calendar" and

4791

# "Access to Cloud Platform". Users can consent to a scope for an application,

4792

# giving it permission to access that data on their behalf.

4793

#

4794

# OAuth scope specifications should be fairly coarse grained; a user will need

4795

# to see and understand the text description of what your scope means.

4796

#

4797

# In most cases: use one or at most two OAuth scopes for an entire family of

4798

# products. If your product has multiple APIs, you should probably be sharing

4799

# the OAuth scope across all of those APIs.

4800

#

4801

# When you need finer grained OAuth consent screens: talk with your product

4802

# management about how developers will use them in practice.

4803

#

4804

# Please note that even though each of the canonical scopes is enough for a

4805

# request to be accepted and passed to the backend, a request can still fail

4806

# due to the backend requiring additional scopes or permissions.

4807

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4808

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4813

# https://www.googleapis.com/auth/calendar.read

4814

},

4815

"requirements": [ # Requirements for additional authentication providers.

4816

{ # User-defined authentication requirements, including support for

4817

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4818

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

4823

"audiences": "A String", # The list of JWT

4824

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4825

# that are allowed to access. A JWT containing any of these audiences will

4826

# be accepted. When this setting is absent, only JWTs with audience

4827

# "https://Service_name/API_name"

4828

# will be accepted. For example, if no audiences are in the setting,

4829

# LibraryService API will only accept JWTs with the following audience

4830

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4835

# bookstore_web.apps.googleusercontent.com

4836

},

4837

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

4838

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

4839

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

4840

#

4841

# For requests without credentials, if the service control environment is

4842

# specified, each incoming request **must** be associated with a service

4843

# consumer. This can be done by passing an API key that belongs to a consumer

4844

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4845

"selector": "A String", # Selects the methods to which this rule applies.

4846

#

4847

# Refer to selector for syntax details.

4848

},

4849

],

4850

"providers": [ # Defines a set of authentication providers that a service supports.

4851

{ # Configuration for an anthentication provider, including support for

4852

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4853

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4854

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4855

# Optional if the key set document:

4856

# - can be retrieved from

4857

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4858

# of the issuer.

4859

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4860

#

4861

# Example: https://www.googleapis.com/oauth2/v1/certs

4862

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4863

# `AuthRequirement.provider_id`.

4864

#

4865

# Example: "bookstore_auth".

4866

"issuer": "A String", # Identifies the principal that issued the JWT. See

4867

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4868

# Usually a URL or an email address.

4869

#

4870

# Example: https://securetoken.google.com

4871

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4876

"rules": [ # A list of usage rules that apply to individual API methods.

4877

#

4878

# **NOTE:** All service configuration rules follow "last one wins" order.

4879

{ # Usage configuration rules for the service.

4880

#

4881

# NOTE: Under development.

4882

#

4883

#

4884

# Use this rule to configure unregistered calls for the service. Unregistered

4885

# calls are calls that do not contain consumer project identity.

4886

# (Example: calls that do not contain an API key).

4887

# By default, API methods do not allow unregistered calls, and each method call

4888

# must be identified by a consumer project identity. Use this rule to

4889

# allow/disallow unregistered calls.

4890

#

4891

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4897

#

4898

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4903

# allow_unregistered_calls: true

4904

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4905

# methods in all APIs.

4906

#

4907

# Refer to selector for syntax details.

4908

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4909

},

4910

],

4911

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4912

# service. Each requirement is of the form <service.name>/<requirement-id>;

4913

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

4918

# influence interpretation of the configuration, for example, to

4919

# determine defaults. This is documented together with applicable

4920

# options. The current default for the config version itself is `3`.

4921

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

4922

# Members of this project can manage the service configuration,

4923

# manage consumption of the service, etc.

4924

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

4925

# HttpRule, each specifying the mapping of an RPC method

4926

# to one or more HTTP REST API methods.

4927

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4928

#

4929

# **NOTE:** All service configuration rules follow "last one wins" order.

4930

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

4931

# REST APIs. The mapping determines what portions of the request

4932

# message are populated from the path, query parameters, or body of

4933

# the HTTP request. The mapping is typically specified as an

4934

# `google.api.http` annotation, see "google/api/annotations.proto"

4935

# for details.

4936

#

4937

# The mapping consists of a field specifying the path template and

4938

# method kind. The path template can refer to fields in the request

4939

# message, as in the example below which describes a REST GET

4940

# operation on a resource collection of messages:

4941

#

4942

# ```proto

4943

# service Messaging {

4944

# rpc GetMessage(GetMessageRequest) returns (Message) {

4945

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4946

# }

4947

# }

4948

# message GetMessageRequest {

4949

# message SubMessage {

4950

# string subfield = 1;

4951

# }

4952

# string message_id = 1; // mapped to the URL

4953

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4954

# }

4955

# message Message {

4956

# string text = 1; // content of the resource

# }

# ```

#

# This definition enables an automatic, bidrectional mapping of HTTP

4961

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4966

#

4967

# In general, not only fields but also field paths can be referenced

4968

# from a path pattern. Fields mapped to the path pattern cannot be

4969

# repeated and must have a primitive (non-message) type.

4970

#

4971

# Any fields in the request message which are not bound by the path

4972

# pattern automatically become (optional) HTTP query

4973

# parameters. Assume the following definition of the request message:

4974

#

4975

# ```proto

4976

# message GetMessageRequest {

4977

# message SubMessage {

4978

# string subfield = 1;

4979

# }

4980

# string message_id = 1; // mapped to the URL

4981

# int64 revision = 2; // becomes a parameter

4982

# 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"))`

4991

#

4992

# Note that fields which are mapped to HTTP parameters must have a

4993

# primitive type or a repeated primitive type. Message types are not

4994

# allowed. In the case of a repeated type, the parameter can be

4995

# repeated in the URL, as in `...?param=A&param=B`.

4996

#

4997

# For HTTP method kinds which allow a request body, the `body` field

4998

# specifies the mapping. Consider a REST update method on the

4999

# message resource collection:

5000

#

5001

# ```proto

5002

# service Messaging {

5003

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

5004

# option (google.api.http) = {

5005

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

5011

# string message_id = 1; // mapped to the URL

5012

# Message message = 2; // mapped to the body

# }

# ```

#

# The following HTTP JSON to RPC mapping is enabled, where the

5017

# representation of the JSON in the request body is determined by

5018

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

5023

#

5024

# The special name `*` can be used in the body mapping to define that

5025

# every field not bound by the path template should be mapped to the

5026

# request body. This enables the following alternative definition of

# the update method:

#

# ```proto

# service Messaging {

5031

# rpc UpdateMessage(Message) returns (Message) {

5032

# option (google.api.http) = {

5033

# 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!")`

5049

#

5050

# Note that when using `*` in the body mapping, it is not possible to

5051

# have HTTP parameters, as all fields not bound by the path end in

5052

# the body. This makes this option more rarely used in practice of

5053

# defining REST APIs. The common usage of `*` is in custom methods

5054

# which don't use the URL at all for transferring data.

5055

#

5056

# It is possible to define multiple HTTP methods for one RPC by using

5057

# the `additional_bindings` option. Example:

5058

#

5059

# ```proto

5060

# service Messaging {

5061

# rpc GetMessage(GetMessageRequest) returns (Message) {

5062

# option (google.api.http) = {

5063

# get: "/v1/messages/{message_id}"

5064

# additional_bindings {

5065

# get: "/v1/users/{user_id}/messages/{message_id}"

# }

# };

# }

# }

# message GetMessageRequest {

5071

# string message_id = 1;

5072

# 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")`

5082

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

5083

#

5084

# # Rules for HTTP mapping

5085

#

5086

# The rules for mapping HTTP path, query parameters, and body fields

5087

# to the request message are as follows:

5088

#

5089

# 1. The `body` field specifies either `*` or a field path, or is

5090

# omitted. If omitted, it assumes there is no HTTP body.

5091

# 2. Leaf fields (recursive expansion of nested messages in the

5092

# request) can be classified into three types:

5093

# (a) Matched in the URL template.

5094

# (b) Covered by body (if body is `*`, everything except (a) fields;

5095

# else everything under the body field)

5096

# (c) All other fields.

5097

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

5098

# 4. Any body sent with an HTTP request can contain only (b) fields.

5099

#

5100

# The syntax of the path template is as follows:

5101

#

5102

# Template = "/" Segments [ Verb ] ;

5103

# Segments = Segment { "/" Segment } ;

5104

# Segment = "*" | "**" | LITERAL | Variable ;

5105

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5106

# FieldPath = IDENT { "." IDENT } ;

5107

# Verb = ":" LITERAL ;

5108

#

5109

# The syntax `*` matches a single path segment. It follows the semantics of

5110

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

5111

# Expansion.

5112

#

5113

# The syntax `**` matches zero or more path segments. It follows the semantics

5114

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

5115

# Expansion.

5116

#

5117

# The syntax `LITERAL` matches literal text in the URL path.

5118

#

5119

# The syntax `Variable` matches the entire path as specified by its template;

5120

# this nested template must not contain further variables. If a variable

5121

# matches a single path segment, its template may be omitted, e.g. `{var}`

5122

# is equivalent to `{var=*}`.

5123

#

5124

# NOTE: the field paths in variables and in the `body` must not refer to

5125

# repeated fields or map fields.

5126

#

5127

# Use CustomHttpPattern to specify any HTTP method that is not included in the

5128

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

5129

# a given URL path rule. The wild-card rule is useful for services that provide

5130

# content to Web (HTML) clients.

5131

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

5132

# `*` for mapping all fields not captured by the path pattern to the HTTP

5133

# body. NOTE: the referred field must not be a repeated field and must be

5134

# present at the top-level of response message type.

5135

"get": "A String", # Used for listing and getting information about resources.

5136

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

5137

# [][google.bytestream.RestByteStream] as an API to your

5138

# configuration.

5139

# [][google.bytestream.RestByteStream] as an API to your

5140

# configuration.

5141

"enabled": True or False, # Whether download is enabled.

5142

},

5143

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

5144

# not contain an `additional_bindings` field themselves (that is,

5145

# the nesting may only be one level deep).

5146

# Object with schema name: HttpRule

5147

],

5148

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

5149

# [][google.bytestream.RestByteStream] as an API to your

5150

# configuration.

5151

# [][google.bytestream.RestByteStream] as an API to your

5152

# configuration.

5153

"enabled": True or False, # Whether upload is enabled.

5154

},

5155

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

5156

"path": "A String", # The path matched by this custom verb.

5157

"kind": "A String", # The name of this custom HTTP verb.

5158

},

5159

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

5160

# response. Other response fields are ignored. This field is optional. When

5161

# not set, the response message will be used as HTTP body of response.

5162

# NOTE: the referred field must be not a repeated field and must be present

5163

# at the top-level of response message type.

5164

"put": "A String", # Used for updating a resource.

5165

"patch": "A String", # Used for updating a resource.

5166

"post": "A String", # Used for creating a resource.

5167

"selector": "A String", # Selects methods to which this rule applies.

5168

#

5169

# Refer to selector for syntax details.

5170

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

5175

# of the google.protobuf.Api needs to be provided by the configuration

5176

# author, as the remaining fields will be derived from the IDL during the

5177

# normalization process. It is an error to specify an API interface here

5178

# which cannot be resolved against the associated IDL files.

5179

{ # Api is a light-weight descriptor for a protocol buffer service.

5180

"methods": [ # The methods of this api, in unspecified order.

5181

{ # Method represents a method of an api.

5182

"name": "A String", # The simple name of this method.

5183

"requestStreaming": True or False, # If true, the request is streamed.

5184

"responseTypeUrl": "A String", # The URL of the output message type.

5185

"requestTypeUrl": "A String", # A URL of the input message type.

5186

"responseStreaming": True or False, # If true, the response is streamed.

5187

"syntax": "A String", # The source syntax of this method.

5188

"options": [ # Any metadata attached to the method.

5189

{ # A protocol buffer option, which can be attached to a message, field,

5190

# enumeration, etc.

5191

"name": "A String", # The option's name. For example, `"java_package"`.

5192

"value": { # The option's value. For example, `"com.google.protobuf"`.

5193

"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

5200

# message.

5201

# protobuf element, like the file in which it is defined.

5202

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5203

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5204

},

5205

"mixins": [ # Included APIs. See Mixin.

5206

{ # Declares an API to be included in this API. The including API must

5207

# redeclare all the methods from the included API, but documentation

5208

# and options are inherited as follows:

5209

#

5210

# - If after comment and whitespace stripping, the documentation

5211

# string of the redeclared method is empty, it will be inherited

5212

# from the original method.

5213

#

5214

# - Each annotation belonging to the service config (http,

5215

# visibility) which is not set in the redeclared method will be

5216

# inherited.

5217

#

5218

# - If an http annotation is inherited, the path pattern will be

5219

# modified as follows. Any version prefix will be replaced by the

5220

# version of the including API plus the root path if specified.

5221

#

5222

# Example of a simple mixin:

5223

#

5224

# package google.acl.v1;

5225

# service AccessControl {

5226

# // Get the underlying ACL object.

5227

# rpc GetAcl(GetAclRequest) returns (Acl) {

5228

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

5233

# service Storage {

5234

# // rpc GetAcl(GetAclRequest) returns (Acl);

5235

#

5236

# // Get a data record.

5237

# rpc GetData(GetDataRequest) returns (Data) {

5238

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

5243

#

5244

# apis:

5245

# - name: google.storage.v2.Storage

5246

# mixins:

5247

# - name: google.acl.v1.AccessControl

5248

#

5249

# The mixin construct implies that all methods in `AccessControl` are

5250

# also declared with same name and request/response types in

5251

# `Storage`. A documentation generator or annotation processor will

5252

# see the effective `Storage.GetAcl` method after inherting

5253

# documentation and annotations as follows:

5254

#

5255

# service Storage {

5256

# // Get the underlying ACL object.

5257

# rpc GetAcl(GetAclRequest) returns (Acl) {

5258

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

5264

#

5265

# If the `root` field in the mixin is specified, it should be a

5266

# relative path under which inherited HTTP paths are placed. Example:

5267

#

5268

# apis:

5269

# - name: google.storage.v2.Storage

5270

# mixins:

5271

# - name: google.acl.v1.AccessControl

5272

# root: acls

5273

#

5274

# This implies the following inherited HTTP annotation:

5275

#

5276

# service Storage {

5277

# // Get the underlying ACL object.

5278

# rpc GetAcl(GetAclRequest) returns (Acl) {

5279

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

5284

# are rooted.

5285

"name": "A String", # The fully qualified name of the API which is included.

5286

},

5287

],

5288

"syntax": "A String", # The source syntax of the service.

5289

"version": "A String", # A version string for this api. If specified, must have the form

5290

# `major-version.minor-version`, as in `1.10`. If the minor version

5291

# is omitted, it defaults to zero. If the entire version field is

5292

# empty, the major version is derived from the package name, as

5293

# outlined below. If the field is not empty, the version in the

5294

# package name will be verified to be consistent with what is

5295

# provided here.

5296

#

5297

# The versioning schema uses [semantic

5298

# versioning](http://semver.org) where the major version number

5299

# indicates a breaking change and the minor version an additive,

5300

# non-breaking change. Both version numbers are signals to users

5301

# what to expect from different versions, and should be carefully

5302

# chosen based on the product plan.

5303

#

5304

# The major version is also reflected in the package name of the

5305

# API, which must end in `v<major-version>`, as in

5306

# `google.feature.v1`. For major versions 0 and 1, the suffix can

5307

# be omitted. Zero major versions must only be used for

5308

# experimental, none-GA apis.

5309

"options": [ # Any metadata attached to the API.

5310

{ # A protocol buffer option, which can be attached to a message, field,

5311

# enumeration, etc.

5312

"name": "A String", # The option's name. For example, `"java_package"`.

5313

"value": { # The option's value. For example, `"com.google.protobuf"`.

5314

"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

5319

# followed by the api's simple name.

5320

},

5321

],

5322

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5323

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5331

# - google.foo.v1.AnotherError

5332

"rules": [ # The list of custom error rules that apply to individual API messages.

5333

#

5334

# **NOTE:** All service configuration rules follow "last one wins" order.

5335

{ # A custom error rule.

5336

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5337

# objects of this type will be filtered when they appear in error payload.

5338

"selector": "A String", # Selects messages to which this rule applies.

5339

#

5340

# Refer to selector for syntax details.

5341

},

5342

],

5343

"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.

5348

# elements. Restrictions are specified using visibility labels

5349

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

5350

#

5351

# Users and projects can have access to more than one visibility label. The

5352

# effective visibility for multiple labels is the union of each label's

5353

# elements, plus any unrestricted elements.

5354

#

5355

# If an element and its parents have no restrictions, visibility is

5356

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5363

# restriction: TRUSTED_TESTER

5364

# - selector: google.calendar.Calendar.Delegate

5365

# restriction: GOOGLE_INTERNAL

5366

#

5367

# Here, all methods are publicly visible except for the restricted methods

5368

# EnhancedSearch and Delegate.

5369

"rules": [ # A list of visibility rules that apply to individual API elements.

5370

#

5371

# **NOTE:** All service configuration rules follow "last one wins" order.

5372

{ # A visibility rule provides visibility configuration for an individual API

5373

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5374

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

5375

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5376

#

5377

# If a rule has multiple labels, removing one of the labels but not all of

5378

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5385

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

5386

#

5387

# Removing GOOGLE_INTERNAL from this restriction will break clients that

5388

# rely on this method and only had access to it through GOOGLE_INTERNAL.

5389

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

5390

#

5391

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

5396

{ # Defines a metric type and its schema.

5397

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5398

# Use sentence case without an ending period, for example "Request count".

5399

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5400

"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]

5401

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5402

"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]

5403

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5404

"labels": [ # The set of labels that can be used to describe a specific instance of this

5405

# metric type. For example, the

5406

# `compute.googleapis.com/instance/network/received_bytes_count` metric type

5407

# has a label, `loadbalanced`, that specifies whether the traffic was

5408

# received through a load balanced IP address.

5409

{ # A description of a label.

5410

"valueType": "A String", # The type of data that can be assigned to the label.

5411

"description": "A String", # A human-readable description for the label.

5412

"key": "A String", # The label key.

5413

},

5414

],

5415

"type": "A String", # The metric type including a DNS name prefix, for example

5416

# `"compute.googleapis.com/instance/cpu/utilization"`. Metric types

5417

# should use a natural hierarchical grouping such as the following:

5418

#

5419

# compute.googleapis.com/instance/cpu/utilization

5420

# compute.googleapis.com/instance/disk/read_ops_count

5421

# compute.googleapis.com/instance/network/received_bytes_count

5422

#

5423

# Note that if the metric type changes, the monitoring data will be

5424

# discontinued, and anything depends on it will break, such as monitoring

5425

# dashboards, alerting rules and quota limits. Therefore, once a metric has

5426

# been published, its type should be immutable.

5427

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

5428

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

5429

# supported units are a subset of [The Unified Code for Units of

5430

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5431

#

5432

# **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)

5447

# * `P` peta (10**15)

5448

# * `E` exa (10**18)

5449

# * `Z` zetta (10**21)

5450

# * `Y` yotta (10**24)

5451

# * `m` milli (10**-3)

5452

# * `u` micro (10**-6)

5453

# * `n` nano (10**-9)

5454

# * `p` pico (10**-12)

5455

# * `f` femto (10**-15)

5456

# * `a` atto (10**-18)

5457

# * `z` zepto (10**-21)

5458

# * `y` yocto (10**-24)

5459

# * `Ki` kibi (2**10)

5460

# * `Mi` mebi (2**20)

5461

# * `Gi` gibi (2**30)

5462

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5467

#

5468

# The grammar also includes these connectors:

5469

#

5470

# * `/` division (as an infix operator, e.g. `1/s`).

5471

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5472

#

5473

# The grammar for a unit is as follows:

5474

#

5475

# Expression = Component { "." Component } { "/" Component } ;

5476

#

5477

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5487

# equivalent to `1` if it is used alone. For examples,

5488

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5489

# * `NAME` is a sequence of non-blank printable ASCII characters not

5490

# containing '{' or '}'.

5491

"name": "A String", # Resource name. The format of the name may vary between different

5492

# implementations. For examples:

5493

#

5494

# projects/{project_id}/metricDescriptors/{type=**}

5495

# metricDescriptors/{type=**}

5496

},

5497

],

5498

"enums": [ # A list of all enum types included in this API service. Enums

5499

# referenced directly or indirectly by the `apis` are automatically

5500

# included. Enums which are not referenced but shall be included

5501

# should be listed here by name. Example:

5502

#

5503

# enums:

5504

# - name: google.someapi.v1.SomeEnum

5505

{ # Enum type definition.

5506

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5507

# protobuf element, like the file in which it is defined.

5508

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5509

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5510

},

5511

"enumvalue": [ # Enum value definitions.

5512

{ # Enum value definition.

5513

"number": 42, # Enum value number.

5514

"options": [ # Protocol buffer options.

5515

{ # A protocol buffer option, which can be attached to a message, field,

5516

# enumeration, etc.

5517

"name": "A String", # The option's name. For example, `"java_package"`.

5518

"value": { # The option's value. For example, `"com.google.protobuf"`.

5519

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

5524

},

5525

],

5526

"options": [ # Protocol buffer options.

5527

{ # A protocol buffer option, which can be attached to a message, field,

5528

# enumeration, etc.

5529

"name": "A String", # The option's name. For example, `"java_package"`.

5530

"value": { # The option's value. For example, `"com.google.protobuf"`.

5531

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

5536

"syntax": "A String", # The source syntax.

5537

},

5538

],

5539

"types": [ # A list of all proto message types included in this API service.

5540

# Types referenced directly or indirectly by the `apis` are

5541

# automatically included. Messages which are not referenced but

5542

# shall be included, such as types used by the `google.protobuf.Any` type,

5543

# should be listed here by name. Example:

5544

#

5545

# types:

5546

# - name: google.protobuf.Int32

5547

{ # A protocol buffer message type.

5548

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5549

"A String",

5550

],

5551

"name": "A String", # The fully qualified message name.

5552

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5553

# protobuf element, like the file in which it is defined.

5554

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5555

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5556

},

5557

"syntax": "A String", # The source syntax.

5558

"fields": [ # The list of fields.

5559

{ # A single field of a message type.

5560

"kind": "A String", # The field type.

5561

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5562

# types. The first type has index 1; zero means the type is not in the list.

5563

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5564

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5565

"name": "A String", # The field name.

5566

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5567

"jsonName": "A String", # The field JSON name.

5568

"number": 42, # The field number.

5569

"cardinality": "A String", # The field cardinality.

5570

"options": [ # The protocol buffer options.

5571

{ # A protocol buffer option, which can be attached to a message, field,

5572

# enumeration, etc.

5573

"name": "A String", # The option's name. For example, `"java_package"`.

5574

"value": { # The option's value. For example, `"com.google.protobuf"`.

5575

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5580

},

5581

],

5582

"options": [ # The protocol buffer options.

5583

{ # A protocol buffer option, which can be attached to a message, field,

5584

# enumeration, etc.

5585

"name": "A String", # The option's name. For example, `"java_package"`.

5586

"value": { # The option's value. For example, `"com.google.protobuf"`.

5587

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5593

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5594

#

5595

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5596

# producer and consumer projects. In the example, the `activity_history`

5597

# log is sent to both the producer and consumer projects, whereas the

5598

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5599

#

5600

# monitored_resources:

5601

# - type: library.googleapis.com/branch

5602

# labels:

5603

# - key: /city

5604

# description: The city where the library branch is located in.

5605

# - key: /name

5606

# description: The name of the branch.

5607

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5608

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5609

# labels:

5610

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5611

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5612

# logging:

5613

# producer_destinations:

5614

# - monitored_resource: library.googleapis.com/branch

5615

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5616

# - activity_history

5617

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5618

# consumer_destinations:

5619

# - monitored_resource: library.googleapis.com/branch

5620

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5621

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5622

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5623

# There can be multiple producer destinations, each one must have a

5624

# different monitored resource type. A log can be used in at most

5625

# one producer destination.

5626

{ # Configuration of a specific logging destination (the producer project

5627

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5628

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5629

# Service.monitored_resources section.

5630

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5631

# be defined in the Service.logs section. If the log name is

5632

# not a domain scoped name, it will be automatically prefixed with

5633

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

"consumerDestinations": [ # Logging configurations for sending logs to the consumer project.

5639

# There can be multiple consumer destinations, each one must have a

5640

# different monitored resource type. A log can be used in at most

5641

# one consumer destination.

5642

{ # Configuration of a specific logging destination (the producer project

5643

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5644

"monitoredResource": "A String", # The monitored resource type. The type must be defined in the

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5645

# Service.monitored_resources section.

5646

"logs": [ # Names of the logs to be sent to this destination. Each name must

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

5647

# be defined in the Service.logs section. If the log name is

5648

# not a domain scoped name, it will be automatically prefixed with

5649

# the service name followed by "/".

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

"A String",

],

},

],

},

"name": "A String", # The DNS address at which this service is available,

5656

# e.g. `calendar.googleapis.com`.

5657

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5658

#

5659

# Example:

5660

# <pre><code>documentation:

5661

# summary: >

5662

# The Google Calendar API gives access

5663

# to most calendar features.

5664

# pages:

5665

# - name: Overview

5666

# content: (== include google/foo/overview.md ==)

5667

# - name: Tutorial

5668

# content: (== include google/foo/tutorial.md ==)

5669

# subpages;

5670

# - name: Java

5671

# content: (== include google/foo/tutorial_java.md ==)

5672

# rules:

5673

# - selector: google.calendar.Calendar.Get

5674

# description: >

5675

# ...

5676

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5681

# standard markdown features, definition lists, tables and fenced

5682

# code blocks are supported. Section headers can be provided and are

5683

# interpreted relative to the section nesting of the context where

5684

# a documentation fragment is embedded.

5685

#

5686

# Documentation from the IDL is merged with documentation defined

5687

# via the config at normalization time, where documentation provided

5688

# by config rules overrides IDL provided.

5689

#

5690

# A number of constructs specific to the API platform are supported

5691

# in documentation text.

5692

#

5693

# In order to reference a proto element, the following

5694

# notation can be used:

5695

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5696

# To override the display text used for the link, this can be used:

5697

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5698

# Text can be excluded from doc using the following notation:

5699

# <pre><code>(-- internal comment --)</code></pre>

5700

# Comments can be made conditional using a visibility label. The below

5701

# text will be only rendered if the `BETA` label is available:

5702

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5703

# A few directives are available in documentation. Note that

5704

# directives must appear on a single line to be properly

5705

# identified. The `include` directive includes a markdown file from

5706

# an external source:

5707

# <pre><code>(== include path/to/file ==)</code></pre>

5708

# The `resource_for` directive marks a message to be the resource of

5709

# a collection in REST view. If it is not specified, tools attempt

5710

# to infer the resource from the operations in a collection:

5711

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5712

# The directive `suppress_warning` does not directly affect documentation

5713

# and is documented together with service config validation.

5714

"rules": [ # A list of documentation rules that apply to individual API elements.

5715

#

5716

# **NOTE:** All service configuration rules follow "last one wins" order.

5717

{ # A documentation rule provides information about individual API elements.

5718

"description": "A String", # Description of the selected API(s).

5719

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5720

# element is marked as `deprecated`.

5721

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5722

# qualified name of the element which may end in "*", indicating a wildcard.

5723

# Wildcards are only allowed at the end and for a whole component of the

5724

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5725

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

5730

# <pre><code>documentation:

5731

# summary: ...

5732

# overview: (== include overview.md ==)

5733

# </code></pre>

5734

# This is a shortcut for the following declaration (using pages style):

5735

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5740

# </code></pre>

5741

# Note: you cannot specify both `overview` field and `pages` field.

5742

"summary": "A String", # A short summary of what the service does. Can only be provided by

5743

# plain text.

5744

"pages": [ # The top level pages for the documentation set.

5745

{ # Represents a documentation page. A page can contain subpages to represent

5746

# nested documentation set structure.

5747

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5748

# to include content from a Markdown file.

5749

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5750

# honored in the generated docset.

5751

# Object with schema name: Page

5752

],

5753

"name": "A String", # The name of the page. It will be used as an identity of the page to

5754

# generate URI of the page, text of the link to this page in navigation,

5755

# etc. The full page name (start from the root page name to this page

5756

# concatenated with `.`) can be used as reference to the page in your

5757

# documentation. For example:

5758

# <pre><code>pages:

5759

# - name: Tutorial

5760

# content: (== include tutorial.md ==)

5761

# subpages:

5762

# - name: Java

5763

# content: (== include tutorial_java.md ==)

5764

# </code></pre>

5765

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

5770

},

5771

"systemTypes": [ # A list of all proto message types included in this API service.

5772

# It serves similar purpose as [google.api.Service.types], except that

5773

# these types are not needed by user-defined APIs. Therefore, they will not

5774

# show up in the generated discovery doc. This field should only be used

5775

# to define system APIs in ESF.

5776

{ # A protocol buffer message type.

5777

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5778

"A String",

5779

],

5780

"name": "A String", # The fully qualified message name.

5781

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5782

# protobuf element, like the file in which it is defined.

5783

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5784

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5785

},

5786

"syntax": "A String", # The source syntax.

5787

"fields": [ # The list of fields.

5788

{ # A single field of a message type.

5789

"kind": "A String", # The field type.

5790

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5791

# types. The first type has index 1; zero means the type is not in the list.

5792

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5793

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5794

"name": "A String", # The field name.

5795

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5796

"jsonName": "A String", # The field JSON name.

5797

"number": 42, # The field number.

5798

"cardinality": "A String", # The field cardinality.

5799

"options": [ # The protocol buffer options.

5800

{ # A protocol buffer option, which can be attached to a message, field,

5801

# enumeration, etc.

5802

"name": "A String", # The option's name. For example, `"java_package"`.

5803

"value": { # The option's value. For example, `"com.google.protobuf"`.

5804

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5809

},

5810

],

5811

"options": [ # The protocol buffer options.

5812

{ # A protocol buffer option, which can be attached to a message, field,

5813

# enumeration, etc.

5814

"name": "A String", # The option's name. For example, `"java_package"`.

5815

"value": { # The option's value. For example, `"com.google.protobuf"`.

5816

"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

5831

# - google.rpc.context.OriginContext

5832

#

5833

# The above specifies that all methods in the API request

5834

# `google.rpc.context.ProjectContext` and

5835

# `google.rpc.context.OriginContext`.

5836

#

5837

# Available context types are defined in package

5838

# `google.rpc.context`.

5839

"rules": [ # A list of RPC context rules that apply to individual API methods.

5840

#

5841

# **NOTE:** All service configuration rules follow "last one wins" order.

5842

{ # A context rule provides information about the context for an individual API

5843

# element.

5844

"provided": [ # A list of full type names of provided contexts.

5845

"A String",

5846

],

5847

"requested": [ # A list of full type names of requested contexts.

5848

"A String",

5849

],

5850

"selector": "A String", # Selects the methods to which this rule applies.

5851

#

5852

# Refer to selector for syntax details.

5853

},

5854

],

5855

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5856

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5857

# with the same name as the service is automatically generated to service all

5858

# defined APIs.

5859

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5860

# A service may expose any number of endpoints, and all endpoints share the

5861

# same service configuration, such as quota configuration and monitoring

5862

# configuration.

5863

#

5864

# Example service configuration:

5865

#

5866

# name: library-example.googleapis.com

5867

# endpoints:

5868

# # Below entry makes 'google.example.library.v1.Library'

5869

# # API be served from endpoint address library-example.googleapis.com.

5870

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5871

# # it to decide whether the subsequent cross-origin request is

5872

# # allowed to proceed.

5873

# - name: library-example.googleapis.com

5874

# apis: google.example.library.v1.Library

5875

# allow_cors: true

5876

# # Below entry makes 'google.example.library.v1.Library'

5877

# # API be served from endpoint address

5878

# # google.example.library-example.v1.LibraryManager.

5879

# - name: library-manager.googleapis.com

5880

# apis: google.example.library.v1.LibraryManager

5881

# # BNS address for a borg job. Can specify a task by appending

5882

# # "/taskId" (e.g. "/0") to the job spec.

5883

#

5884

# Example OpenAPI extension for endpoint with allow_cors set to true:

#

# {

# "swagger": "2.0",

# "info": {

# "description": "A simple..."

5890

# },

5891

# "host": "MY_PROJECT_ID.appspot.com",

5892

# "x-google-endpoints": [{

5893

# "name": "MY_PROJECT_ID.appspot.com",

5894

# "allow_cors": "true"

5895

# }]

5896

# }

5897

"allowCors": True or False, # Allowing

5898

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5899

# cross-domain traffic, would allow the backends served from this endpoint to

5900

# receive and respond to HTTP OPTIONS requests. The response will be used by

5901

# the browser to determine whether the subsequent cross-origin request is

5902

# allowed to proceed.

5903

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

5904

# please specify multiple google.api.Endpoint for each of the intented

5905

# alias.

5906

#

5907

# Additional names that this endpoint will be hosted on.

5908

"A String",

5909

],

5910

"features": [ # The list of features enabled on this endpoint.

5911

"A String",

5912

],

5913

"name": "A String", # The canonical name of this endpoint.

5914

"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_next">list_next(previous_request, previous_response)</code>

5926

<pre>Retrieves the next page of results.

5927

5928

Args:

5929

previous_request: The request for the previous page. (required)

5930

previous_response: The response from the request for the previous page. (required)

5931

5932

Returns:

5933

A request object that you can call 'execute()' on to request the next

5934

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="submit">submit(serviceName=None, body, x__xgafv=None)</code>

5940

<pre>Creates a new service configuration (version) for a managed service based

5941

on

5942

user-supplied configuration source files (for example: OpenAPI

5943

Specification). This method stores the source configurations as well as the

5944

generated service configuration. To rollout the service configuration to

5945

other services,

5946

please call CreateServiceRollout.

5947

5948

Operation<response: SubmitConfigSourceResponse>

5949

5950

Args:

5951

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5952

for naming requirements. For example: `example.googleapis.com`. (required)

5953

body: object, The request body. (required)

5954

The object takes the form of:

5955

5956

{ # Request message for SubmitConfigSource method.

5957

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

5958

# `google.api.Service` configuration based on the `ConfigSource` provided,

5959

# but the generated config and the sources will NOT be persisted.

5960

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

5961

# defined by `google.api.Service`.

5962

"files": [ # Set of source configuration files that are used to generate a service

5963

# configuration (`google.api.Service`).

5964

{ # Generic specification of a source configuration file

5965

"fileContents": "A String", # The bytes that constitute the file.

5966

"fileType": "A String", # The type of configuration file this represents.

5967

"filePath": "A String", # The file name of the configuration file (full or relative path).

5968

},

5969

],

5970

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

5971

# by the client for tracking purpose. If empty, the server may choose to

5972

# generate one instead.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5983

5984

{ # This resource represents a long-running operation that is the result of a

5985

# network API call.

5986

"metadata": { # Service-specific metadata associated with the operation. It typically

5987

# contains progress information and common metadata such as create time.

5988

# Some services might not provide such metadata. Any method that returns a

5989

# long-running operation should document the metadata type, if any.

5990

"a_key": "", # Properties of the object. Contains field @type with type URL.

5991

},

5992

"done": True or False, # If the value is `false`, it means the operation is still in progress.

5993

# If true, the operation is completed, and either `error` or `response` is

5994

# available.

5995

"response": { # The normal response of the operation in case of success. If the original

5996

# method returns no data on success, such as `Delete`, the response is

5997

# `google.protobuf.Empty`. If the original method is standard

5998

# `Get`/`Create`/`Update`, the response should be the resource. For other

5999

# methods, the response should have the type `XxxResponse`, where `Xxx`

6000

# is the original method name. For example, if the original method name

6001

# is `TakeSnapshot()`, the inferred response type is

6002

# `TakeSnapshotResponse`.

6003

"a_key": "", # Properties of the object. Contains field @type with type URL.

6004

},

6005

"name": "A String", # The server-assigned name, which is only unique within the same service that

6006

# originally returns it. If you use the default HTTP mapping, the

6007

# `name` should have the format of `operations/some/unique/name`.

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame^]

6008

"error": { # The `Status` type defines a logical error model that is suitable for different # The error result of the operation in case of failure or cancellation.

Jon Wayne Parrott