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

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

[diff] [blame^]

120

# authentication:

121

# providers:

122

# - id: google_calendar_auth

123

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

124

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

Jon Wayne Parrott

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

[diff] [blame]

125

# rules:

Jon Wayne Parrott

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

[diff] [blame^]

126

# - selector: "*"

127

# requirements:

128

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

129

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

130

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

131

# monitoring, etc.

132

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

133

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

134

},

135

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

136

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

137

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

138

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

139

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

140

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

141

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

142

#

143

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

144

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

145

# by the API.

146

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

147

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

148

# The maximum length of this value is 256 characters.

149

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

150

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

151

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

152

{ # A description of a label.

153

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

154

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

155

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

156

},

157

],

158

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

Jon Wayne Parrott

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

[diff] [blame]

159

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

160

# without any article or other determiners. For example,

161

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

162

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

163

# be used in documentation.

164

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

165

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

166

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

167

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

168

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

169

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

170

},

171

],

172

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

173

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

174

#

175

# - name: library.googleapis.com/activity_history

176

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

177

# display_name: Activity

178

# labels:

179

# - key: /customer_id

180

# description: Identifier of a library customer

181

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

182

# Runtime requests that contain labels not specified here are

183

# considered invalid.

184

{ # A description of a label.

185

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

186

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

187

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

188

},

189

],

190

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

191

# the user interface and should be concise.

192

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

193

# the documentation and can contain details.

194

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

195

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

196

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

197

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

198

},

199

],

Sai Cheemalapati

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

[diff] [blame]

200

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

Jon Wayne Parrott

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

[diff] [blame]

201

#

202

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

203

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

204

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

205

# change the names of the system parameters.

206

"rules": [ # Define system parameters.

207

#

208

# The parameters defined here will override the default parameters

209

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

210

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

211

# and names is implementation-dependent.

212

#

Jon Wayne Parrott

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

[diff] [blame^]

213

# Example: define api key for all methods

Jon Wayne Parrott

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

[diff] [blame]

214

#

Jon Wayne Parrott

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

[diff] [blame^]

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

221

#

Jon Wayne Parrott

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

[diff] [blame]

222

#

223

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

224

#

Jon Wayne Parrott

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

[diff] [blame^]

225

# system_parameters

226

# rules:

227

# - selector: "/ListShelves"

228

# parameters:

229

# - name: api_key

230

# http_header: Api-Key1

231

# - name: api_key

232

# http_header: Api-Key2

Jon Wayne Parrott

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

[diff] [blame]

233

#

234

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

235

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

236

# methods.

237

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

238

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

239

# names are used the behavior is implementation-dependent.

240

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

241

# parameter-dependent.

242

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

243

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

244

# is implementation-dependent.

245

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

246

# sensitive.

Jon Wayne Parrott

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

[diff] [blame^]

247

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

Jon Wayne Parrott

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

[diff] [blame]

248

"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

253

# methods in all APIs.

254

#

255

# Refer to selector for syntax details.

},

],

},

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

260

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

261

#

262

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

263

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

264

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

265

#

266

# Refer to selector for syntax details.

267

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

268

# default depends on the deployment context.

269

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

270

},

271

],

272

},

Sai Cheemalapati

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

[diff] [blame]

273

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

Jon Wayne Parrott

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

[diff] [blame]

274

#

275

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

276

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

277

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

278

# to both producer and consumer projects, whereas the

279

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

280

# consumer project.

281

#

282

# monitored_resources:

283

# - type: library.googleapis.com/branch

284

# labels:

285

# - key: /city

286

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

287

# - key: /name

288

# description: The name of the branch.

289

# metrics:

290

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

295

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

300

# monitoring:

301

# producer_destinations:

302

# - monitored_resource: library.googleapis.com/branch

303

# metrics:

304

# - library.googleapis.com/book/returned_count

305

# consumer_destinations:

306

# - monitored_resource: library.googleapis.com/branch

307

# metrics:

308

# - library.googleapis.com/book/returned_count

309

# - library.googleapis.com/book/overdue_count

310

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

311

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

312

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

313

# one producer destination.

314

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

315

# or the consumer project).

316

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

317

# Service.monitored_resources section.

318

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

319

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

"A String",

],

},

],

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

325

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

326

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

327

# one consumer destination.

328

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

329

# or the consumer project).

330

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

331

# Service.monitored_resources section.

332

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

333

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

"A String",

],

},

],

},

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

340

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

341

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

342

# generate one instead.

343

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

344

#

345

# Example for an API targeted for external use:

346

#

347

# name: calendar.googleapis.com

348

# authentication:

Jon Wayne Parrott

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

[diff] [blame^]

349

# providers:

350

# - id: google_calendar_auth

351

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

352

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

Jon Wayne Parrott

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

[diff] [blame]

353

# rules:

354

# - selector: "*"

Jon Wayne Parrott

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

[diff] [blame^]

355

# requirements:

356

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

357

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

358

#

359

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

360

{ # Authentication rules for the service.

361

#

362

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

363

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

364

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

365

# request.

366

#

367

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

368

# ignored.

369

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

370

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

371

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

372

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

373

#

374

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

375

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

376

#

377

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

378

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

379

# the OAuth scope across all of those APIs.

380

#

381

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

382

# management about how developers will use them in practice.

383

#

384

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

385

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

386

# due to the backend requiring additional scopes or permissions.

387

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

388

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

#

# Example:

#

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

393

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

394

},

395

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

396

{ # User-defined authentication requirements, including support for

397

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

398

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

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

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

[diff] [blame^]

403

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

404

# implemented and accepted in all the runtime components.

405

#

406

# The list of JWT

Jon Wayne Parrott

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

[diff] [blame]

407

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

408

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

409

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

410

# "https://Service_name/API_name"

411

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

412

# LibraryService API will only accept JWTs with the following audience

413

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

418

# bookstore_web.apps.googleusercontent.com

419

},

420

],

Jon Wayne Parrott

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

[diff] [blame]

421

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

422

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

423

#

424

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

425

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

426

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

427

# project.

Jon Wayne Parrott

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

[diff] [blame]

428

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

429

#

430

# Refer to selector for syntax details.

431

},

432

],

433

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

434

{ # Configuration for an anthentication provider, including support for

435

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

436

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

437

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

438

# Optional if the key set document:

439

# - can be retrieved from

440

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

441

# of the issuer.

442

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

443

#

444

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

Jon Wayne Parrott

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

[diff] [blame^]

445

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

446

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

447

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

448

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

449

# "https://Service_name/API_name"

450

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

451

# LibraryService API will only accept JWTs with the following audience

452

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

457

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

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

[diff] [blame]

458

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

459

# `AuthRequirement.provider_id`.

460

#

461

# Example: "bookstore_auth".

462

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

463

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

464

# Usually a URL or an email address.

465

#

466

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

467

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

},

],

},

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

472

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

473

#

474

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

475

{ # Usage configuration rules for the service.

476

#

477

# NOTE: Under development.

478

#

479

#

480

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

481

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

482

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

483

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

484

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

485

# allow/disallow unregistered calls.

486

#

487

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

493

#

494

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

#

# usage:

# rules:

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

499

# allow_unregistered_calls: true

500

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

501

# methods in all APIs.

502

#

503

# Refer to selector for syntax details.

504

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

505

},

506

],

Jon Wayne Parrott

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

[diff] [blame^]

507

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

508

# service producer.

509

#

510

# Google Service Management currently only supports

511

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

512

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

513

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

514

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

Jon Wayne Parrott

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

[diff] [blame]

515

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

516

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

517

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

"A String",

],

},

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

522

# influence interpretation of the configuration, for example, to

523

# determine defaults. This is documented together with applicable

524

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

525

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

526

# Members of this project can manage the service configuration,

527

# manage consumption of the service, etc.

528

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

529

# HttpRule, each specifying the mapping of an RPC method

530

# to one or more HTTP REST API methods.

531

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

532

#

533

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

534

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

535

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

536

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

537

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

538

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

539

# for details.

540

#

541

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

542

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

543

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

544

# operation on a resource collection of messages:

545

#

Jon Wayne Parrott

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

[diff] [blame^]

546

#

547

# service Messaging {

548

# rpc GetMessage(GetMessageRequest) returns (Message) {

549

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

550

# }

551

# }

552

# message GetMessageRequest {

553

# message SubMessage {

554

# string subfield = 1;

555

# }

556

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

557

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

558

# }

559

# message Message {

560

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

561

# }

562

#

563

# The same http annotation can alternatively be expressed inside the

564

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

569

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

Jon Wayne Parrott

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

[diff] [blame]

570

#

571

# This definition enables an automatic, bidrectional mapping of HTTP

572

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

577

#

578

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

579

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

580

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

581

#

582

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

583

# pattern automatically become (optional) HTTP query

584

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

585

#

Jon Wayne Parrott

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

[diff] [blame^]

586

#

587

# message GetMessageRequest {

588

# message SubMessage {

589

# string subfield = 1;

590

# }

591

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

592

# int64 revision = 2; // becomes a parameter

593

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

594

# }

595

#

Jon Wayne Parrott

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

[diff] [blame]

596

#

597

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

602

#

603

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

604

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

605

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

606

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

607

#

608

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

609

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

610

# message resource collection:

611

#

Jon Wayne Parrott

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

[diff] [blame^]

612

#

613

# service Messaging {

614

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

615

# option (google.api.http) = {

616

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

622

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

623

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

624

# }

625

#

Jon Wayne Parrott

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

[diff] [blame]

626

#

627

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

628

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

629

# protos JSON encoding:

#

# HTTP | RPC

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

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

634

#

635

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

636

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

637

# request body. This enables the following alternative definition of

638

# the update method:

639

#

Jon Wayne Parrott

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

[diff] [blame^]

640

# service Messaging {

641

# rpc UpdateMessage(Message) returns (Message) {

642

# option (google.api.http) = {

643

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

650

# string text = 2;

651

# }

652

#

Jon Wayne Parrott

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

[diff] [blame]

653

#

654

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

659

#

660

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

661

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

662

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

663

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

664

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

665

#

666

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

667

# the `additional_bindings` option. Example:

668

#

Jon Wayne Parrott

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

[diff] [blame^]

669

# service Messaging {

670

# rpc GetMessage(GetMessageRequest) returns (Message) {

671

# option (google.api.http) = {

672

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

673

# additional_bindings {

674

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

675

# }

676

# };

Jon Wayne Parrott

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

[diff] [blame]

677

# }

Jon Wayne Parrott

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

[diff] [blame^]

678

# }

679

# message GetMessageRequest {

680

# string message_id = 1;

681

# string user_id = 2;

682

# }

683

#

Jon Wayne Parrott

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

[diff] [blame]

684

#

685

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

691

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

692

#

693

# # Rules for HTTP mapping

694

#

695

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

696

# to the request message are as follows:

697

#

698

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

699

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

700

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

701

# request) can be classified into three types:

702

# (a) Matched in the URL template.

703

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

704

# else everything under the body field)

705

# (c) All other fields.

706

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

707

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

708

#

709

# The syntax of the path template is as follows:

710

#

711

# Template = "/" Segments [ Verb ] ;

712

# Segments = Segment { "/" Segment } ;

713

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

714

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

715

# FieldPath = IDENT { "." IDENT } ;

716

# Verb = ":" LITERAL ;

717

#

718

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

719

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

720

# Expansion.

721

#

722

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

723

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

Jon Wayne Parrott

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

[diff] [blame^]

724

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

Jon Wayne Parrott

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

[diff] [blame]

725

#

726

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

727

#

728

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

729

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

730

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

731

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

732

#

733

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

734

# repeated fields or map fields.

735

#

736

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

737

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

738

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

739

# content to Web (HTML) clients.

740

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

741

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

742

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

Jon Wayne Parrott

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

[diff] [blame^]

743

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

Jon Wayne Parrott

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

[diff] [blame]

744

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

745

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

746

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

747

# configuration.

748

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

749

# configuration.

750

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

751

},

752

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

753

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

754

# the nesting may only be one level deep).

755

# Object with schema name: HttpRule

756

],

757

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

758

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

759

# configuration.

760

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

761

# configuration.

762

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

763

},

764

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

765

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

766

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

767

},

768

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

769

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

770

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

771

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

772

# at the top-level of response message type.

773

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

774

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

775

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

776

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

777

#

778

# Refer to selector for syntax details.

779

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

},

],

},

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

784

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

785

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

786

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

787

# which cannot be resolved against the associated IDL files.

788

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

789

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

790

{ # Method represents a method of an api.

791

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

792

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

793

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

794

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

795

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

796

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

797

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

798

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

799

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

800

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

801

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

802

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

803

# `"google.api.http"`.

804

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

805

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

806

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

807

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

808

"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

815

# message.

816

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

817

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

818

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

819

},

820

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

821

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

822

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

823

# and options are inherited as follows:

824

#

825

# - If after comment and whitespace stripping, the documentation

826

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

827

# from the original method.

828

#

829

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

830

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

831

# inherited.

832

#

833

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

834

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

835

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

836

#

837

# Example of a simple mixin:

838

#

839

# package google.acl.v1;

840

# service AccessControl {

841

# // Get the underlying ACL object.

842

# rpc GetAcl(GetAclRequest) returns (Acl) {

843

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

# }

# }

#

# package google.storage.v2;

848

# service Storage {

849

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

850

#

851

# // Get a data record.

852

# rpc GetData(GetDataRequest) returns (Data) {

853

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

# }

# }

#

# Example of a mixin configuration:

858

#

859

# apis:

860

# - name: google.storage.v2.Storage

861

# mixins:

862

# - name: google.acl.v1.AccessControl

863

#

864

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

865

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

866

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

867

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

868

# documentation and annotations as follows:

869

#

870

# service Storage {

871

# // Get the underlying ACL object.

872

# rpc GetAcl(GetAclRequest) returns (Acl) {

873

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

# }

# ...

# }

#

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

879

#

880

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

881

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

882

#

883

# apis:

884

# - name: google.storage.v2.Storage

885

# mixins:

886

# - name: google.acl.v1.AccessControl

887

# root: acls

888

#

889

# This implies the following inherited HTTP annotation:

890

#

891

# service Storage {

892

# // Get the underlying ACL object.

893

# rpc GetAcl(GetAclRequest) returns (Acl) {

894

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

# }

# ...

# }

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

899

# are rooted.

900

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

901

},

902

],

903

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

904

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

905

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

906

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

907

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

908

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

909

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

910

# provided here.

911

#

912

# The versioning schema uses [semantic

913

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

914

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

915

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

916

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

917

# chosen based on the product plan.

918

#

919

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

920

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

921

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

922

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

923

# experimental, none-GA apis.

924

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

925

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

926

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

927

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

928

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

929

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

930

# `"google.api.http"`.

931

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

932

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

933

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

934

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

935

"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

940

# followed by the api's simple name.

941

},

942

],

943

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

944

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

952

# - google.foo.v1.AnotherError

953

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

954

#

955

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

956

{ # A custom error rule.

957

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

958

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

959

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

960

#

961

# Refer to selector for syntax details.

962

},

963

],

964

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

969

# elements. Restrictions are specified using visibility labels

970

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

971

#

972

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

973

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

974

# elements, plus any unrestricted elements.

975

#

976

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

977

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

984

# restriction: TRUSTED_TESTER

985

# - selector: google.calendar.Calendar.Delegate

986

# restriction: GOOGLE_INTERNAL

987

#

988

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

989

# EnhancedSearch and Delegate.

990

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

991

#

992

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

993

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

994

# element.

Sai Cheemalapati

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

[diff] [blame]

995

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

996

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

Jon Wayne Parrott

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

[diff] [blame]

997

#

998

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

999

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1006

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1007

#

1008

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1009

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

1010

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

1011

#

1012

# Refer to selector for syntax details.

},

],

},

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

Jon Wayne Parrott

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

[diff] [blame^]

1017

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

1018

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

1019

# existing data unusable.

Jon Wayne Parrott

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

[diff] [blame]

1020

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

1021

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

1022

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

1023

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

1024

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

Jon Wayne Parrott

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

[diff] [blame]

1025

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

1026

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

Jon Wayne Parrott

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

[diff] [blame^]

1027

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

1028

# instance of this metric type. For example, the

1029

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

1030

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

1031

# you can look at latencies for successful responses or just

1032

# for responses that failed.

Jon Wayne Parrott

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

[diff] [blame]

1033

{ # A description of a label.

1034

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

1035

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

1036

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

1037

},

1038

],

Jon Wayne Parrott

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

[diff] [blame^]

1039

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

1040

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

1041

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

1042

# grouping. For example:

Jon Wayne Parrott

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

[diff] [blame]

1043

#

Jon Wayne Parrott

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

[diff] [blame^]

1044

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

1045

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

Jon Wayne Parrott

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

[diff] [blame]

1046

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

1047

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

1048

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

1049

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

1050

#

1051

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

1066

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

1067

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

1068

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

1069

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

1070

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

1071

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

1072

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

1073

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

1074

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

1075

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

1076

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

1077

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

1078

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

1079

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

1080

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

1081

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

#

# **Grammar**

#

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

1086

#

1087

# The grammar also includes these connectors:

1088

#

1089

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

1090

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

1091

#

1092

# The grammar for a unit is as follows:

1093

#

1094

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

1095

#

1096

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1106

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

1107

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

1108

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

1109

# containing '{' or '}'.

Jon Wayne Parrott

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

[diff] [blame^]

1110

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

1111

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

1112

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

1113

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

1114

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

1115

# metric within the GCP project 123456789:

Jon Wayne Parrott

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

[diff] [blame]

1116

#

Jon Wayne Parrott

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

[diff] [blame^]

1117

# "projects/123456789/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

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

[diff] [blame]

1118

},

1119

],

1120

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

1121

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

1122

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

1123

# should be listed here by name. Example:

1124

#

1125

# enums:

1126

# - name: google.someapi.v1.SomeEnum

1127

{ # Enum type definition.

1128

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

1129

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

1130

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

1131

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

1132

},

1133

"enumvalue": [ # Enum value definitions.

1134

{ # Enum value definition.

1135

"number": 42, # Enum value number.

1136

"options": [ # Protocol buffer options.

1137

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

1138

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1139

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

1140

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

1141

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

1142

# `"google.api.http"`.

1143

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

1144

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

1145

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

1146

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1147

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

},

},

],

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

1152

},

1153

],

1154

"options": [ # Protocol buffer options.

1155

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

1156

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1157

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

1158

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

1159

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

1160

# `"google.api.http"`.

1161

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

1162

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

1163

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

1164

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1165

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

},

},

],

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

1170

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

1171

},

1172

],

1173

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

1174

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

1175

# automatically included. Messages which are not referenced but

1176

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

1177

# should be listed here by name. Example:

1178

#

1179

# types:

1180

# - name: google.protobuf.Int32

1181

{ # A protocol buffer message type.

1182

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

1183

"A String",

1184

],

1185

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

1186

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

1187

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

1188

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

1189

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

1190

},

1191

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

1192

"fields": [ # The list of fields.

1193

{ # A single field of a message type.

1194

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

1195

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

1196

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

1197

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

1198

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

1199

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

1200

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

1201

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

1202

"number": 42, # The field number.

1203

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

1204

"options": [ # The protocol buffer options.

1205

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

1206

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1207

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

1208

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

1209

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

1210

# `"google.api.http"`.

1211

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

1212

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

1213

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

1214

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1215

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

},

},

],

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

1220

},

1221

],

1222

"options": [ # The protocol buffer options.

1223

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

1224

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1225

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

1226

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

1227

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

1228

# `"google.api.http"`.

1229

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

1230

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

1231

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

1232

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1233

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1239

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

Jon Wayne Parrott

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

[diff] [blame]

1240

#

1241

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

Sai Cheemalapati

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

[diff] [blame]

1242

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

1243

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

1244

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

Jon Wayne Parrott

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

[diff] [blame]

1245

#

1246

# monitored_resources:

1247

# - type: library.googleapis.com/branch

1248

# labels:

1249

# - key: /city

1250

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

1251

# - key: /name

1252

# description: The name of the branch.

1253

# logs:

Sai Cheemalapati

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

[diff] [blame]

1254

# - name: activity_history

Jon Wayne Parrott

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

[diff] [blame]

1255

# labels:

1256

# - key: /customer_id

Sai Cheemalapati

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

[diff] [blame]

1257

# - name: purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1258

# logging:

1259

# producer_destinations:

1260

# - monitored_resource: library.googleapis.com/branch

1261

# logs:

Sai Cheemalapati

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

[diff] [blame]

1262

# - activity_history

1263

# - purchase_history

Jon Wayne Parrott

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

[diff] [blame]

1264

# consumer_destinations:

1265

# - monitored_resource: library.googleapis.com/branch

1266

# logs:

Sai Cheemalapati

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

[diff] [blame]

1267

# - activity_history

Jon Wayne Parrott

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

[diff] [blame]

1268

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

1269

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

1270

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

1271

# one producer destination.

1272

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

1273

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1274

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

1275

# Service.monitored_resources section.

1276

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

1277

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

1278

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

1279

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

1285

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

1286

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

1287

# one consumer destination.

1288

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

1289

# or the consumer project).

Sai Cheemalapati

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

[diff] [blame]

1290

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

1291

# Service.monitored_resources section.

1292

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

1293

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

1294

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

1295

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

1302

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

1303

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

1304

#

1305

# Example:

1306

# <pre><code>documentation:

1307

# summary: >

1308

# The Google Calendar API gives access

1309

# to most calendar features.

1310

# pages:

1311

# - name: Overview

1312

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

1313

# - name: Tutorial

1314

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

1315

# subpages;

1316

# - name: Java

1317

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

1318

# rules:

1319

# - selector: google.calendar.Calendar.Get

1320

# description: >

1321

# ...

1322

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1327

# standard markdown features, definition lists, tables and fenced

1328

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

1329

# interpreted relative to the section nesting of the context where

1330

# a documentation fragment is embedded.

1331

#

1332

# Documentation from the IDL is merged with documentation defined

1333

# via the config at normalization time, where documentation provided

1334

# by config rules overrides IDL provided.

1335

#

1336

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

1337

# in documentation text.

1338

#

1339

# In order to reference a proto element, the following

1340

# notation can be used:

1341

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

1342

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

1343

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

1344

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

1345

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

1346

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

1347

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

1348

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

1349

# A few directives are available in documentation. Note that

1350

# directives must appear on a single line to be properly

1351

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

1352

# an external source:

1353

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

1354

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

1355

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

1356

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

1357

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

1358

# The directive `suppress_warning` does not directly affect documentation

1359

# and is documented together with service config validation.

1360

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

1361

#

1362

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

1363

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

1364

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

1365

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

1366

# element is marked as `deprecated`.

1367

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

1368

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

1369

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

1370

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

1371

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

# is used.

},

],

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

1376

# <pre><code>documentation:

1377

# summary: ...

1378

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

1379

# </code></pre>

1380

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

1381

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1386

# </code></pre>

1387

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

1388

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

1389

# plain text.

1390

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

1391

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

1392

# nested documentation set structure.

1393

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

1394

# to include content from a Markdown file.

1395

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

1396

# honored in the generated docset.

1397

# Object with schema name: Page

1398

],

1399

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

1400

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

1401

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

1402

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

1403

# documentation. For example:

1404

# <pre><code>pages:

1405

# - name: Tutorial

1406

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

1407

# subpages:

1408

# - name: Java

1409

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

1410

# </code></pre>

1411

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

# `Java`.

},

],

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

1416

},

1417

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

1418

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

1419

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

1420

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

1421

# to define system APIs in ESF.

1422

{ # A protocol buffer message type.

1423

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

1424

"A String",

1425

],

1426

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

1427

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

1428

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

1429

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

1430

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

1431

},

1432

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

1433

"fields": [ # The list of fields.

1434

{ # A single field of a message type.

1435

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

1436

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

1437

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

1438

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

1439

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

1440

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

1441

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

1442

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

1443

"number": 42, # The field number.

1444

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

1445

"options": [ # The protocol buffer options.

1446

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

1447

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1448

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

1449

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

1450

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

1451

# `"google.api.http"`.

1452

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

1453

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

1454

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

1455

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1456

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

},

},

],

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

1461

},

1462

],

1463

"options": [ # The protocol buffer options.

1464

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

1465

# enumeration, etc.

Jon Wayne Parrott

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

[diff] [blame^]

1466

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

1467

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

1468

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

1469

# `"google.api.http"`.

1470

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

1471

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

1472

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

1473

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

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

[diff] [blame]

1474

"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

1489

# - google.rpc.context.OriginContext

1490

#

1491

# The above specifies that all methods in the API request

1492

# `google.rpc.context.ProjectContext` and

1493

# `google.rpc.context.OriginContext`.

1494

#

1495

# Available context types are defined in package

1496

# `google.rpc.context`.

1497

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

1498

#

1499

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

1500

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

1501

# element.

1502

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

1503

"A String",

1504

],

1505

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

1506

"A String",

1507

],

1508

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

1509

#

1510

# Refer to selector for syntax details.

1511

},

1512

],

1513

},

Sai Cheemalapati

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

[diff] [blame]

1514

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

1515

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

1516

# defined APIs.

1517

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

1518

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

1519

# same service configuration, such as quota configuration and monitoring

1520

# configuration.

1521

#

1522

# Example service configuration:

1523

#

1524

# name: library-example.googleapis.com

1525

# endpoints:

1526

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

1527

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

1528

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

1529

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

1530

# # allowed to proceed.

1531

# - name: library-example.googleapis.com

Sai Cheemalapati

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

[diff] [blame]

1532

# allow_cors: true

Sai Cheemalapati

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

[diff] [blame]

1533

"allowCors": True or False, # Allowing

1534

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

1535

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

1536

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

1537

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

1538

# allowed to proceed.

1539

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

1540

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

1541

# alias.

1542

#

1543

# Additional names that this endpoint will be hosted on.

1544

"A String",

1545

],

1546

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

1547

"A String",

1548

],

1549

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

1550

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

"A String",

],

},

],

Jon Wayne Parrott

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

[diff] [blame]

1555

}

1556

1557

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1564

Sai Cheemalapati

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

[diff] [blame]

1565

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

1566

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

1567

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

1568

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

1569

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

1574

# config_version: 3

Jon Wayne Parrott

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

[diff] [blame]

1575

# name: calendar.googleapis.com

1576

# title: Google Calendar API

1577

# apis:

Sai Cheemalapati

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

[diff] [blame]

1578

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

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

[diff] [blame^]

1579

# authentication:

1580

# providers:

1581

# - id: google_calendar_auth

1582

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

1583

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

Jon Wayne Parrott

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

[diff] [blame]

1584

# rules:

Jon Wayne Parrott

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

[diff] [blame^]

1585

# - selector: "*"

1586

# requirements:

1587

# provider_id: google_calendar_auth

Jon Wayne Parrott

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

[diff] [blame]

1588

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

1589

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

1590

# monitoring, etc.

1591

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

1592

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

1593

},

1594

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

1595

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

1596

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

1597

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

1598

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

1599

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

1600

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

1601

#

1602

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

1603

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

1604

# by the API.

1605

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

1606

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

1607

# The maximum length of this value is 256 characters.

1608

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

1609

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

1610

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

1611

{ # A description of a label.

1612

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

1613

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

1614

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

1615

},

1616

],

1617

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

1618

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

1619

# without any article or other determiners. For example,

1620

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

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

[diff] [blame]

1621

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

1622

# be used in documentation.

1623

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

1624

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

1625

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

1626

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

1627

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

1628

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

1629

},

1630

],

1631

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

1632

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

1633

#

1634

# - name: library.googleapis.com/activity_history

1635

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

1636

# display_name: Activity

1637

# labels:

1638

# - key: /customer_id

1639

# description: Identifier of a library customer

1640

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

1641

# Runtime requests that contain labels not specified here are

1642

# considered invalid.

1643

{ # A description of a label.

1644

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

1645

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

1646

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

1647

},

1648

],

1649

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

1650

# the user interface and should be concise.

1651

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

1652

# the documentation and can contain details.

1653

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

1654

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

1655

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

1656

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

1657

},

1658

],

Sai Cheemalapati

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

[diff] [blame]

1659

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

Jon Wayne Parrott

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

[diff] [blame]

1660

#

1661

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

1662

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

1663

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

1664

# change the names of the system parameters.

1665

"rules": [ # Define system parameters.

1666

#

1667

# The parameters defined here will override the default parameters

1668

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

1669

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

1670

# and names is implementation-dependent.

1671

#

Jon Wayne Parrott

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

[diff] [blame^]

1672

# Example: define api key for all methods

Jon Wayne Parrott

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

[diff] [blame]

1673

#

Jon Wayne Parrott

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

[diff] [blame^]

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

1680

#

Jon Wayne Parrott

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

[diff] [blame]

1681

#

1682

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

1683

#

Jon Wayne Parrott

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

[diff] [blame^]

1684

# system_parameters

1685

# rules:

1686

# - selector: "/ListShelves"

1687

# parameters:

1688

# - name: api_key

1689

# http_header: Api-Key1

1690

# - name: api_key

1691

# http_header: Api-Key2

Jon Wayne Parrott

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

[diff] [blame]

1692

#

1693

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

1694

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

1695

# methods.

1696

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

1697

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

1698

# names are used the behavior is implementation-dependent.

1699

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

1700

# parameter-dependent.

1701

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

1702

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

1703

# is implementation-dependent.

1704

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

1705

# sensitive.

Jon Wayne Parrott

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

[diff] [blame^]

1706

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

Jon Wayne Parrott

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

[diff] [blame]

1707

"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

1712

# methods in all APIs.

1713

#

1714

# Refer to selector for syntax details.

},

],

},

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

1719

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

1720

#

1721

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

1722

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

1723

"selector": "A String", # Selects the methods to which this rule applies.

1724

#

1725

# Refer to selector for syntax details.

1726

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

1727

# default depends on the deployment context.

1728

"address": "A String", # The address of the API backend.

1729

},

1730

],

1731

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

1732

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1733

#

1734

# The example below shows how to configure monitored resources and metrics

1735

# for monitoring. In the example, a monitored resource and two metrics are

1736

# defined. The `library.googleapis.com/book/returned_count` metric is sent

1737

# to both producer and consumer projects, whereas the

1738

# `library.googleapis.com/book/overdue_count` metric is only sent to the

1739

# consumer project.

1740

#

1741

# monitored_resources:

1742

# - type: library.googleapis.com/branch

1743

# labels:

1744

# - key: /city

1745

# description: The city where the library branch is located in.

1746

# - key: /name

1747

# description: The name of the branch.

1748

# metrics:

1749

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

1754

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

1759

# monitoring:

1760

# producer_destinations:

1761

# - monitored_resource: library.googleapis.com/branch

1762

# metrics:

1763

# - library.googleapis.com/book/returned_count

1764

# consumer_destinations:

1765

# - monitored_resource: library.googleapis.com/branch

1766

# metrics:

1767

# - library.googleapis.com/book/returned_count

1768

# - library.googleapis.com/book/overdue_count

1769

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

1770

# There can be multiple producer destinations, each one must have a

1771

# different monitored resource type. A metric can be used in at most

1772

# one producer destination.

1773

{ # Configuration of a specific monitoring destination (the producer project

1774

# or the consumer project).

1775

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1776

# Service.monitored_resources section.

1777

"metrics": [ # Names of the metrics to report to this monitoring destination.

1778

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

1784

# There can be multiple consumer destinations, each one must have a

1785

# different monitored resource type. A metric can be used in at most

1786

# one consumer destination.

1787

{ # Configuration of a specific monitoring destination (the producer project

1788

# or the consumer project).

1789

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

1790

# Service.monitored_resources section.

1791

"metrics": [ # Names of the metrics to report to this monitoring destination.

1792

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

1799

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

1800

# by the client for tracking purpose. If empty, the server may choose to

1801

# generate one instead.

1802

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

1803

#

1804

# Example for an API targeted for external use:

1805

#

1806

# name: calendar.googleapis.com

1807

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

1808

# providers:

1809

# - id: google_calendar_auth

1810

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

1811

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1812

# rules:

1813

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

1814

# requirements:

1815

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1816

"rules": [ # A list of authentication rules that apply to individual API methods.

1817

#

1818

# **NOTE:** All service configuration rules follow "last one wins" order.

1819

{ # Authentication rules for the service.

1820

#

1821

# By default, if a method has any authentication requirements, every request

1822

# must include a valid credential matching one of the requirements.

1823

# It's an error to include more than one kind of credential in a single

1824

# request.

1825

#

1826

# If a method doesn't have any auth requirements, request credentials will be

1827

# ignored.

1828

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

1829

# there are scopes defined for "Read-only access to Google Calendar" and

1830

# "Access to Cloud Platform". Users can consent to a scope for an application,

1831

# giving it permission to access that data on their behalf.

1832

#

1833

# OAuth scope specifications should be fairly coarse grained; a user will need

1834

# to see and understand the text description of what your scope means.

1835

#

1836

# In most cases: use one or at most two OAuth scopes for an entire family of

1837

# products. If your product has multiple APIs, you should probably be sharing

1838

# the OAuth scope across all of those APIs.

1839

#

1840

# When you need finer grained OAuth consent screens: talk with your product

1841

# management about how developers will use them in practice.

1842

#

1843

# Please note that even though each of the canonical scopes is enough for a

1844

# request to be accepted and passed to the backend, a request can still fail

1845

# due to the backend requiring additional scopes or permissions.

1846

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

1847

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

1852

# https://www.googleapis.com/auth/calendar.read

1853

},

1854

"requirements": [ # Requirements for additional authentication providers.

1855

{ # User-defined authentication requirements, including support for

1856

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

1857

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

1862

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

1863

# implemented and accepted in all the runtime components.

1864

#

1865

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1866

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

1867

# that are allowed to access. A JWT containing any of these audiences will

1868

# be accepted. When this setting is absent, only JWTs with audience

1869

# "https://Service_name/API_name"

1870

# will be accepted. For example, if no audiences are in the setting,

1871

# LibraryService API will only accept JWTs with the following audience

1872

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1877

# bookstore_web.apps.googleusercontent.com

1878

},

1879

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

1880

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

1881

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

1882

#

1883

# For requests without credentials, if the service control environment is

1884

# specified, each incoming request **must** be associated with a service

1885

# consumer. This can be done by passing an API key that belongs to a consumer

1886

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1887

"selector": "A String", # Selects the methods to which this rule applies.

1888

#

1889

# Refer to selector for syntax details.

1890

},

1891

],

1892

"providers": [ # Defines a set of authentication providers that a service supports.

1893

{ # Configuration for an anthentication provider, including support for

1894

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

1895

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

1896

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

1897

# Optional if the key set document:

1898

# - can be retrieved from

1899

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

1900

# of the issuer.

1901

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

1902

#

1903

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

1904

"audiences": "A String", # The list of JWT

1905

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

1906

# that are allowed to access. A JWT containing any of these audiences will

1907

# be accepted. When this setting is absent, only JWTs with audience

1908

# "https://Service_name/API_name"

1909

# will be accepted. For example, if no audiences are in the setting,

1910

# LibraryService API will only accept JWTs with the following audience

1911

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

1916

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1917

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

1918

# `AuthRequirement.provider_id`.

1919

#

1920

# Example: "bookstore_auth".

1921

"issuer": "A String", # Identifies the principal that issued the JWT. See

1922

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

1923

# Usually a URL or an email address.

1924

#

1925

# Example: https://securetoken.google.com

1926

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

1931

"rules": [ # A list of usage rules that apply to individual API methods.

1932

#

1933

# **NOTE:** All service configuration rules follow "last one wins" order.

1934

{ # Usage configuration rules for the service.

1935

#

1936

# NOTE: Under development.

1937

#

1938

#

1939

# Use this rule to configure unregistered calls for the service. Unregistered

1940

# calls are calls that do not contain consumer project identity.

1941

# (Example: calls that do not contain an API key).

1942

# By default, API methods do not allow unregistered calls, and each method call

1943

# must be identified by a consumer project identity. Use this rule to

1944

# allow/disallow unregistered calls.

1945

#

1946

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

1952

#

1953

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

1958

# allow_unregistered_calls: true

1959

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

1960

# methods in all APIs.

1961

#

1962

# Refer to selector for syntax details.

1963

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

1964

},

1965

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

1966

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

1967

# service producer.

1968

#

1969

# Google Service Management currently only supports

1970

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

1971

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

1972

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

1973

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

1974

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

1975

# service. Each requirement is of the form <service.name>/<requirement-id>;

1976

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

1981

# influence interpretation of the configuration, for example, to

1982

# determine defaults. This is documented together with applicable

1983

# options. The current default for the config version itself is `3`.

1984

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

1985

# Members of this project can manage the service configuration,

1986

# manage consumption of the service, etc.

1987

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

1988

# HttpRule, each specifying the mapping of an RPC method

1989

# to one or more HTTP REST API methods.

1990

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

1991

#

1992

# **NOTE:** All service configuration rules follow "last one wins" order.

1993

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

1994

# REST APIs. The mapping determines what portions of the request

1995

# message are populated from the path, query parameters, or body of

1996

# the HTTP request. The mapping is typically specified as an

1997

# `google.api.http` annotation, see "google/api/annotations.proto"

1998

# for details.

1999

#

2000

# The mapping consists of a field specifying the path template and

2001

# method kind. The path template can refer to fields in the request

2002

# message, as in the example below which describes a REST GET

2003

# operation on a resource collection of messages:

2004

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2005

#

2006

# service Messaging {

2007

# rpc GetMessage(GetMessageRequest) returns (Message) {

2008

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

2009

# }

2010

# }

2011

# message GetMessageRequest {

2012

# message SubMessage {

2013

# string subfield = 1;

2014

# }

2015

# string message_id = 1; // mapped to the URL

2016

# SubMessage sub = 2; // `sub.subfield` is url-mapped

2017

# }

2018

# message Message {

2019

# string text = 1; // content of the resource

2020

# }

2021

#

2022

# The same http annotation can alternatively be expressed inside the

2023

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

2028

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2029

#

2030

# This definition enables an automatic, bidrectional mapping of HTTP

2031

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

2036

#

2037

# In general, not only fields but also field paths can be referenced

2038

# from a path pattern. Fields mapped to the path pattern cannot be

2039

# repeated and must have a primitive (non-message) type.

2040

#

2041

# Any fields in the request message which are not bound by the path

2042

# pattern automatically become (optional) HTTP query

2043

# parameters. Assume the following definition of the request message:

2044

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2045

#

2046

# message GetMessageRequest {

2047

# message SubMessage {

2048

# string subfield = 1;

2049

# }

2050

# string message_id = 1; // mapped to the URL

2051

# int64 revision = 2; // becomes a parameter

2052

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

2053

# }

2054

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2055

#

2056

# 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"))`

2061

#

2062

# Note that fields which are mapped to HTTP parameters must have a

2063

# primitive type or a repeated primitive type. Message types are not

2064

# allowed. In the case of a repeated type, the parameter can be

2065

# repeated in the URL, as in `...?param=A&param=B`.

2066

#

2067

# For HTTP method kinds which allow a request body, the `body` field

2068

# specifies the mapping. Consider a REST update method on the

2069

# message resource collection:

2070

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2071

#

2072

# service Messaging {

2073

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

2074

# option (google.api.http) = {

2075

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

2081

# string message_id = 1; // mapped to the URL

2082

# Message message = 2; // mapped to the body

2083

# }

2084

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2085

#

2086

# The following HTTP JSON to RPC mapping is enabled, where the

2087

# representation of the JSON in the request body is determined by

2088

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

2093

#

2094

# The special name `*` can be used in the body mapping to define that

2095

# every field not bound by the path template should be mapped to the

2096

# request body. This enables the following alternative definition of

2097

# the update method:

2098

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2099

# service Messaging {

2100

# rpc UpdateMessage(Message) returns (Message) {

2101

# option (google.api.http) = {

2102

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

2109

# string text = 2;

2110

# }

2111

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2112

#

2113

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

2118

#

2119

# Note that when using `*` in the body mapping, it is not possible to

2120

# have HTTP parameters, as all fields not bound by the path end in

2121

# the body. This makes this option more rarely used in practice of

2122

# defining REST APIs. The common usage of `*` is in custom methods

2123

# which don't use the URL at all for transferring data.

2124

#

2125

# It is possible to define multiple HTTP methods for one RPC by using

2126

# the `additional_bindings` option. Example:

2127

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2128

# service Messaging {

2129

# rpc GetMessage(GetMessageRequest) returns (Message) {

2130

# option (google.api.http) = {

2131

# get: "/v1/messages/{message_id}"

2132

# additional_bindings {

2133

# get: "/v1/users/{user_id}/messages/{message_id}"

2134

# }

2135

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2136

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2137

# }

2138

# message GetMessageRequest {

2139

# string message_id = 1;

2140

# string user_id = 2;

2141

# }

2142

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2143

#

2144

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

2150

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

2151

#

2152

# # Rules for HTTP mapping

2153

#

2154

# The rules for mapping HTTP path, query parameters, and body fields

2155

# to the request message are as follows:

2156

#

2157

# 1. The `body` field specifies either `*` or a field path, or is

2158

# omitted. If omitted, it assumes there is no HTTP body.

2159

# 2. Leaf fields (recursive expansion of nested messages in the

2160

# request) can be classified into three types:

2161

# (a) Matched in the URL template.

2162

# (b) Covered by body (if body is `*`, everything except (a) fields;

2163

# else everything under the body field)

2164

# (c) All other fields.

2165

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

2166

# 4. Any body sent with an HTTP request can contain only (b) fields.

2167

#

2168

# The syntax of the path template is as follows:

2169

#

2170

# Template = "/" Segments [ Verb ] ;

2171

# Segments = Segment { "/" Segment } ;

2172

# Segment = "*" | "**" | LITERAL | Variable ;

2173

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

2174

# FieldPath = IDENT { "." IDENT } ;

2175

# Verb = ":" LITERAL ;

2176

#

2177

# The syntax `*` matches a single path segment. It follows the semantics of

2178

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

2179

# Expansion.

2180

#

2181

# The syntax `**` matches zero or more path segments. It follows the semantics

2182

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2183

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2184

#

2185

# The syntax `LITERAL` matches literal text in the URL path.

2186

#

2187

# The syntax `Variable` matches the entire path as specified by its template;

2188

# this nested template must not contain further variables. If a variable

2189

# matches a single path segment, its template may be omitted, e.g. `{var}`

2190

# is equivalent to `{var=*}`.

2191

#

2192

# NOTE: the field paths in variables and in the `body` must not refer to

2193

# repeated fields or map fields.

2194

#

2195

# Use CustomHttpPattern to specify any HTTP method that is not included in the

2196

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

2197

# a given URL path rule. The wild-card rule is useful for services that provide

2198

# content to Web (HTML) clients.

2199

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

2200

# `*` for mapping all fields not captured by the path pattern to the HTTP

2201

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2202

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2203

"get": "A String", # Used for listing and getting information about resources.

2204

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2205

# [][google.bytestream.RestByteStream] as an API to your

2206

# configuration.

2207

# [][google.bytestream.RestByteStream] as an API to your

2208

# configuration.

2209

"enabled": True or False, # Whether download is enabled.

2210

},

2211

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

2212

# not contain an `additional_bindings` field themselves (that is,

2213

# the nesting may only be one level deep).

2214

# Object with schema name: HttpRule

2215

],

2216

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

2217

# [][google.bytestream.RestByteStream] as an API to your

2218

# configuration.

2219

# [][google.bytestream.RestByteStream] as an API to your

2220

# configuration.

2221

"enabled": True or False, # Whether upload is enabled.

2222

},

2223

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

2224

"path": "A String", # The path matched by this custom verb.

2225

"kind": "A String", # The name of this custom HTTP verb.

2226

},

2227

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

2228

# response. Other response fields are ignored. This field is optional. When

2229

# not set, the response message will be used as HTTP body of response.

2230

# NOTE: the referred field must be not a repeated field and must be present

2231

# at the top-level of response message type.

2232

"put": "A String", # Used for updating a resource.

2233

"patch": "A String", # Used for updating a resource.

2234

"post": "A String", # Used for creating a resource.

2235

"selector": "A String", # Selects methods to which this rule applies.

2236

#

2237

# Refer to selector for syntax details.

2238

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

2243

# of the google.protobuf.Api needs to be provided by the configuration

2244

# author, as the remaining fields will be derived from the IDL during the

2245

# normalization process. It is an error to specify an API interface here

2246

# which cannot be resolved against the associated IDL files.

2247

{ # Api is a light-weight descriptor for a protocol buffer service.

2248

"methods": [ # The methods of this api, in unspecified order.

2249

{ # Method represents a method of an api.

2250

"name": "A String", # The simple name of this method.

2251

"requestStreaming": True or False, # If true, the request is streamed.

2252

"responseTypeUrl": "A String", # The URL of the output message type.

2253

"requestTypeUrl": "A String", # A URL of the input message type.

2254

"responseStreaming": True or False, # If true, the response is streamed.

2255

"syntax": "A String", # The source syntax of this method.

2256

"options": [ # Any metadata attached to the method.

2257

{ # A protocol buffer option, which can be attached to a message, field,

2258

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2259

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2260

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2261

# For custom options, it should be the fully-qualified name. For example,

2262

# `"google.api.http"`.

2263

"value": { # The option's value packed in an Any message. If the value is a primitive,

2264

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2265

# should be used. If the value is an enum, it should be stored as an int32

2266

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2267

"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

2274

# message.

2275

# protobuf element, like the file in which it is defined.

2276

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2277

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2278

},

2279

"mixins": [ # Included APIs. See Mixin.

2280

{ # Declares an API to be included in this API. The including API must

2281

# redeclare all the methods from the included API, but documentation

2282

# and options are inherited as follows:

2283

#

2284

# - If after comment and whitespace stripping, the documentation

2285

# string of the redeclared method is empty, it will be inherited

2286

# from the original method.

2287

#

2288

# - Each annotation belonging to the service config (http,

2289

# visibility) which is not set in the redeclared method will be

2290

# inherited.

2291

#

2292

# - If an http annotation is inherited, the path pattern will be

2293

# modified as follows. Any version prefix will be replaced by the

2294

# version of the including API plus the root path if specified.

2295

#

2296

# Example of a simple mixin:

2297

#

2298

# package google.acl.v1;

2299

# service AccessControl {

2300

# // Get the underlying ACL object.

2301

# rpc GetAcl(GetAclRequest) returns (Acl) {

2302

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

2307

# service Storage {

2308

# // rpc GetAcl(GetAclRequest) returns (Acl);

2309

#

2310

# // Get a data record.

2311

# rpc GetData(GetDataRequest) returns (Data) {

2312

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

2317

#

2318

# apis:

2319

# - name: google.storage.v2.Storage

2320

# mixins:

2321

# - name: google.acl.v1.AccessControl

2322

#

2323

# The mixin construct implies that all methods in `AccessControl` are

2324

# also declared with same name and request/response types in

2325

# `Storage`. A documentation generator or annotation processor will

2326

# see the effective `Storage.GetAcl` method after inherting

2327

# documentation and annotations as follows:

2328

#

2329

# service Storage {

2330

# // Get the underlying ACL object.

2331

# rpc GetAcl(GetAclRequest) returns (Acl) {

2332

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

2338

#

2339

# If the `root` field in the mixin is specified, it should be a

2340

# relative path under which inherited HTTP paths are placed. Example:

2341

#

2342

# apis:

2343

# - name: google.storage.v2.Storage

2344

# mixins:

2345

# - name: google.acl.v1.AccessControl

2346

# root: acls

2347

#

2348

# This implies the following inherited HTTP annotation:

2349

#

2350

# service Storage {

2351

# // Get the underlying ACL object.

2352

# rpc GetAcl(GetAclRequest) returns (Acl) {

2353

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

2358

# are rooted.

2359

"name": "A String", # The fully qualified name of the API which is included.

2360

},

2361

],

2362

"syntax": "A String", # The source syntax of the service.

2363

"version": "A String", # A version string for this api. If specified, must have the form

2364

# `major-version.minor-version`, as in `1.10`. If the minor version

2365

# is omitted, it defaults to zero. If the entire version field is

2366

# empty, the major version is derived from the package name, as

2367

# outlined below. If the field is not empty, the version in the

2368

# package name will be verified to be consistent with what is

2369

# provided here.

2370

#

2371

# The versioning schema uses [semantic

2372

# versioning](http://semver.org) where the major version number

2373

# indicates a breaking change and the minor version an additive,

2374

# non-breaking change. Both version numbers are signals to users

2375

# what to expect from different versions, and should be carefully

2376

# chosen based on the product plan.

2377

#

2378

# The major version is also reflected in the package name of the

2379

# API, which must end in `v<major-version>`, as in

2380

# `google.feature.v1`. For major versions 0 and 1, the suffix can

2381

# be omitted. Zero major versions must only be used for

2382

# experimental, none-GA apis.

2383

"options": [ # Any metadata attached to the API.

2384

{ # A protocol buffer option, which can be attached to a message, field,

2385

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2386

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2387

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2388

# For custom options, it should be the fully-qualified name. For example,

2389

# `"google.api.http"`.

2390

"value": { # The option's value packed in an Any message. If the value is a primitive,

2391

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2392

# should be used. If the value is an enum, it should be stored as an int32

2393

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2394

"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

2399

# followed by the api's simple name.

2400

},

2401

],

2402

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

2403

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

2411

# - google.foo.v1.AnotherError

2412

"rules": [ # The list of custom error rules that apply to individual API messages.

2413

#

2414

# **NOTE:** All service configuration rules follow "last one wins" order.

2415

{ # A custom error rule.

2416

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

2417

# objects of this type will be filtered when they appear in error payload.

2418

"selector": "A String", # Selects messages to which this rule applies.

2419

#

2420

# Refer to selector for syntax details.

2421

},

2422

],

2423

"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.

2428

# elements. Restrictions are specified using visibility labels

2429

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

2430

#

2431

# Users and projects can have access to more than one visibility label. The

2432

# effective visibility for multiple labels is the union of each label's

2433

# elements, plus any unrestricted elements.

2434

#

2435

# If an element and its parents have no restrictions, visibility is

2436

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2443

# restriction: TRUSTED_TESTER

2444

# - selector: google.calendar.Calendar.Delegate

2445

# restriction: GOOGLE_INTERNAL

2446

#

2447

# Here, all methods are publicly visible except for the restricted methods

2448

# EnhancedSearch and Delegate.

2449

"rules": [ # A list of visibility rules that apply to individual API elements.

2450

#

2451

# **NOTE:** All service configuration rules follow "last one wins" order.

2452

{ # A visibility rule provides visibility configuration for an individual API

2453

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2454

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

2455

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2456

#

2457

# If a rule has multiple labels, removing one of the labels but not all of

2458

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

2465

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

2466

#

2467

# Removing GOOGLE_INTERNAL from this restriction will break clients that

2468

# rely on this method and only had access to it through GOOGLE_INTERNAL.

2469

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

2470

#

2471

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2476

{ # Defines a metric type and its schema. Once a metric descriptor is created,

2477

# deleting or altering it stops data collection and makes the metric type's

2478

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2479

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

2480

# Use sentence case without an ending period, for example "Request count".

2481

"description": "A String", # A detailed description of the metric, which can be used in documentation.

2482

"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]

2483

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2484

"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]

2485

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2486

"labels": [ # The set of labels that can be used to describe a specific

2487

# instance of this metric type. For example, the

2488

# `appengine.googleapis.com/http/server/response_latencies` metric

2489

# type has a label for the HTTP response code, `response_code`, so

2490

# you can look at latencies for successful responses or just

2491

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2492

{ # A description of a label.

2493

"valueType": "A String", # The type of data that can be assigned to the label.

2494

"description": "A String", # A human-readable description for the label.

2495

"key": "A String", # The label key.

2496

},

2497

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2498

"type": "A String", # The metric type, including its DNS name prefix. The type is not

2499

# URL-encoded. All user-defined metric types have the DNS name

2500

# `custom.googleapis.com`. Metric types should use a natural hierarchical

2501

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2502

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2503

# "custom.googleapis.com/invoice/paid/amount"

2504

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2505

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

2506

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

2507

# supported units are a subset of [The Unified Code for Units of

2508

# Measure](http://unitsofmeasure.org/ucum.html) standard:

2509

#

2510

# **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)

2525

# * `P` peta (10**15)

2526

# * `E` exa (10**18)

2527

# * `Z` zetta (10**21)

2528

# * `Y` yotta (10**24)

2529

# * `m` milli (10**-3)

2530

# * `u` micro (10**-6)

2531

# * `n` nano (10**-9)

2532

# * `p` pico (10**-12)

2533

# * `f` femto (10**-15)

2534

# * `a` atto (10**-18)

2535

# * `z` zepto (10**-21)

2536

# * `y` yocto (10**-24)

2537

# * `Ki` kibi (2**10)

2538

# * `Mi` mebi (2**20)

2539

# * `Gi` gibi (2**30)

2540

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

2545

#

2546

# The grammar also includes these connectors:

2547

#

2548

# * `/` division (as an infix operator, e.g. `1/s`).

2549

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

2550

#

2551

# The grammar for a unit is as follows:

2552

#

2553

# Expression = Component { "." Component } { "/" Component } ;

2554

#

2555

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

2565

# equivalent to `1` if it is used alone. For examples,

2566

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

2567

# * `NAME` is a sequence of non-blank printable ASCII characters not

2568

# containing '{' or '}'.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2569

"name": "A String", # The resource name of the metric descriptor. Depending on the

2570

# implementation, the name typically includes: (1) the parent resource name

2571

# that defines the scope of the metric type or of its data; and (2) the

2572

# metric's URL-encoded type, which also appears in the `type` field of this

2573

# descriptor. For example, following is the resource name of a custom

2574

# metric within the GCP project 123456789:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2575

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2576

# "projects/123456789/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2577

},

2578

],

2579

"enums": [ # A list of all enum types included in this API service. Enums

2580

# referenced directly or indirectly by the `apis` are automatically

2581

# included. Enums which are not referenced but shall be included

2582

# should be listed here by name. Example:

2583

#

2584

# enums:

2585

# - name: google.someapi.v1.SomeEnum

2586

{ # Enum type definition.

2587

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2588

# protobuf element, like the file in which it is defined.

2589

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2590

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2591

},

2592

"enumvalue": [ # Enum value definitions.

2593

{ # Enum value definition.

2594

"number": 42, # Enum value number.

2595

"options": [ # Protocol buffer options.

2596

{ # A protocol buffer option, which can be attached to a message, field,

2597

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2598

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2599

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2600

# For custom options, it should be the fully-qualified name. For example,

2601

# `"google.api.http"`.

2602

"value": { # The option's value packed in an Any message. If the value is a primitive,

2603

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2604

# should be used. If the value is an enum, it should be stored as an int32

2605

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2606

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

2611

},

2612

],

2613

"options": [ # Protocol buffer options.

2614

{ # A protocol buffer option, which can be attached to a message, field,

2615

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2616

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2617

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2618

# For custom options, it should be the fully-qualified name. For example,

2619

# `"google.api.http"`.

2620

"value": { # The option's value packed in an Any message. If the value is a primitive,

2621

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2622

# should be used. If the value is an enum, it should be stored as an int32

2623

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2624

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

2629

"syntax": "A String", # The source syntax.

2630

},

2631

],

2632

"types": [ # A list of all proto message types included in this API service.

2633

# Types referenced directly or indirectly by the `apis` are

2634

# automatically included. Messages which are not referenced but

2635

# shall be included, such as types used by the `google.protobuf.Any` type,

2636

# should be listed here by name. Example:

2637

#

2638

# types:

2639

# - name: google.protobuf.Int32

2640

{ # A protocol buffer message type.

2641

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2642

"A String",

2643

],

2644

"name": "A String", # The fully qualified message name.

2645

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2646

# protobuf element, like the file in which it is defined.

2647

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2648

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2649

},

2650

"syntax": "A String", # The source syntax.

2651

"fields": [ # The list of fields.

2652

{ # A single field of a message type.

2653

"kind": "A String", # The field type.

2654

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2655

# types. The first type has index 1; zero means the type is not in the list.

2656

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2657

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2658

"name": "A String", # The field name.

2659

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2660

"jsonName": "A String", # The field JSON name.

2661

"number": 42, # The field number.

2662

"cardinality": "A String", # The field cardinality.

2663

"options": [ # The protocol buffer options.

2664

{ # A protocol buffer option, which can be attached to a message, field,

2665

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2666

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2667

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2668

# For custom options, it should be the fully-qualified name. For example,

2669

# `"google.api.http"`.

2670

"value": { # The option's value packed in an Any message. If the value is a primitive,

2671

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2672

# should be used. If the value is an enum, it should be stored as an int32

2673

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2674

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2679

},

2680

],

2681

"options": [ # The protocol buffer options.

2682

{ # A protocol buffer option, which can be attached to a message, field,

2683

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2684

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2685

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2686

# For custom options, it should be the fully-qualified name. For example,

2687

# `"google.api.http"`.

2688

"value": { # The option's value packed in an Any message. If the value is a primitive,

2689

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2690

# should be used. If the value is an enum, it should be stored as an int32

2691

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2692

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2698

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2699

#

2700

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2701

# producer and consumer projects. In the example, the `activity_history`

2702

# log is sent to both the producer and consumer projects, whereas the

2703

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2704

#

2705

# monitored_resources:

2706

# - type: library.googleapis.com/branch

2707

# labels:

2708

# - key: /city

2709

# description: The city where the library branch is located in.

2710

# - key: /name

2711

# description: The name of the branch.

2712

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2713

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2714

# labels:

2715

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2716

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2717

# logging:

2718

# producer_destinations:

2719

# - monitored_resource: library.googleapis.com/branch

2720

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2721

# - activity_history

2722

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2723

# consumer_destinations:

2724

# - monitored_resource: library.googleapis.com/branch

2725

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2726

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2727

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

2728

# There can be multiple producer destinations, each one must have a

2729

# different monitored resource type. A log can be used in at most

2730

# one producer destination.

2731

{ # Configuration of a specific logging destination (the producer project

2732

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2733

"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]

2734

# Service.monitored_resources section.

2735

"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]

2736

# be defined in the Service.logs section. If the log name is

2737

# not a domain scoped name, it will be automatically prefixed with

2738

# 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.

2744

# There can be multiple consumer destinations, each one must have a

2745

# different monitored resource type. A log can be used in at most

2746

# one consumer destination.

2747

{ # Configuration of a specific logging destination (the producer project

2748

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

2749

"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]

2750

# Service.monitored_resources section.

2751

"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]

2752

# be defined in the Service.logs section. If the log name is

2753

# not a domain scoped name, it will be automatically prefixed with

2754

# 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,

2761

# e.g. `calendar.googleapis.com`.

2762

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

2763

#

2764

# Example:

2765

# <pre><code>documentation:

2766

# summary: >

2767

# The Google Calendar API gives access

2768

# to most calendar features.

2769

# pages:

2770

# - name: Overview

2771

# content: (== include google/foo/overview.md ==)

2772

# - name: Tutorial

2773

# content: (== include google/foo/tutorial.md ==)

2774

# subpages;

2775

# - name: Java

2776

# content: (== include google/foo/tutorial_java.md ==)

2777

# rules:

2778

# - selector: google.calendar.Calendar.Get

2779

# description: >

2780

# ...

2781

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

2786

# standard markdown features, definition lists, tables and fenced

2787

# code blocks are supported. Section headers can be provided and are

2788

# interpreted relative to the section nesting of the context where

2789

# a documentation fragment is embedded.

2790

#

2791

# Documentation from the IDL is merged with documentation defined

2792

# via the config at normalization time, where documentation provided

2793

# by config rules overrides IDL provided.

2794

#

2795

# A number of constructs specific to the API platform are supported

2796

# in documentation text.

2797

#

2798

# In order to reference a proto element, the following

2799

# notation can be used:

2800

# <pre><code>[fully.qualified.proto.name][]</code></pre>

2801

# To override the display text used for the link, this can be used:

2802

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

2803

# Text can be excluded from doc using the following notation:

2804

# <pre><code>(-- internal comment --)</code></pre>

2805

# Comments can be made conditional using a visibility label. The below

2806

# text will be only rendered if the `BETA` label is available:

2807

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

2808

# A few directives are available in documentation. Note that

2809

# directives must appear on a single line to be properly

2810

# identified. The `include` directive includes a markdown file from

2811

# an external source:

2812

# <pre><code>(== include path/to/file ==)</code></pre>

2813

# The `resource_for` directive marks a message to be the resource of

2814

# a collection in REST view. If it is not specified, tools attempt

2815

# to infer the resource from the operations in a collection:

2816

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

2817

# The directive `suppress_warning` does not directly affect documentation

2818

# and is documented together with service config validation.

2819

"rules": [ # A list of documentation rules that apply to individual API elements.

2820

#

2821

# **NOTE:** All service configuration rules follow "last one wins" order.

2822

{ # A documentation rule provides information about individual API elements.

2823

"description": "A String", # Description of the selected API(s).

2824

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

2825

# element is marked as `deprecated`.

2826

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

2827

# qualified name of the element which may end in "*", indicating a wildcard.

2828

# Wildcards are only allowed at the end and for a whole component of the

2829

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

2830

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

2835

# <pre><code>documentation:

2836

# summary: ...

2837

# overview: (== include overview.md ==)

2838

# </code></pre>

2839

# This is a shortcut for the following declaration (using pages style):

2840

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

2845

# </code></pre>

2846

# Note: you cannot specify both `overview` field and `pages` field.

2847

"summary": "A String", # A short summary of what the service does. Can only be provided by

2848

# plain text.

2849

"pages": [ # The top level pages for the documentation set.

2850

{ # Represents a documentation page. A page can contain subpages to represent

2851

# nested documentation set structure.

2852

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

2853

# to include content from a Markdown file.

2854

"subpages": [ # Subpages of this page. The order of subpages specified here will be

2855

# honored in the generated docset.

2856

# Object with schema name: Page

2857

],

2858

"name": "A String", # The name of the page. It will be used as an identity of the page to

2859

# generate URI of the page, text of the link to this page in navigation,

2860

# etc. The full page name (start from the root page name to this page

2861

# concatenated with `.`) can be used as reference to the page in your

2862

# documentation. For example:

2863

# <pre><code>pages:

2864

# - name: Tutorial

2865

# content: (== include tutorial.md ==)

2866

# subpages:

2867

# - name: Java

2868

# content: (== include tutorial_java.md ==)

2869

# </code></pre>

2870

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

2875

},

2876

"systemTypes": [ # A list of all proto message types included in this API service.

2877

# It serves similar purpose as [google.api.Service.types], except that

2878

# these types are not needed by user-defined APIs. Therefore, they will not

2879

# show up in the generated discovery doc. This field should only be used

2880

# to define system APIs in ESF.

2881

{ # A protocol buffer message type.

2882

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

2883

"A String",

2884

],

2885

"name": "A String", # The fully qualified message name.

2886

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

2887

# protobuf element, like the file in which it is defined.

2888

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

2889

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

2890

},

2891

"syntax": "A String", # The source syntax.

2892

"fields": [ # The list of fields.

2893

{ # A single field of a message type.

2894

"kind": "A String", # The field type.

2895

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

2896

# types. The first type has index 1; zero means the type is not in the list.

2897

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

2898

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

2899

"name": "A String", # The field name.

2900

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

2901

"jsonName": "A String", # The field JSON name.

2902

"number": 42, # The field number.

2903

"cardinality": "A String", # The field cardinality.

2904

"options": [ # The protocol buffer options.

2905

{ # A protocol buffer option, which can be attached to a message, field,

2906

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2907

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2908

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2909

# For custom options, it should be the fully-qualified name. For example,

2910

# `"google.api.http"`.

2911

"value": { # The option's value packed in an Any message. If the value is a primitive,

2912

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2913

# should be used. If the value is an enum, it should be stored as an int32

2914

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2915

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

2920

},

2921

],

2922

"options": [ # The protocol buffer options.

2923

{ # A protocol buffer option, which can be attached to a message, field,

2924

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

2925

"name": "A String", # The option's name. For protobuf built-in options (options defined in

2926

# descriptor.proto), this is the short name. For example, `"map_entry"`.

2927

# For custom options, it should be the fully-qualified name. For example,

2928

# `"google.api.http"`.

2929

"value": { # The option's value packed in an Any message. If the value is a primitive,

2930

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

2931

# should be used. If the value is an enum, it should be stored as an int32

2932

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

2933

"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

2948

# - google.rpc.context.OriginContext

2949

#

2950

# The above specifies that all methods in the API request

2951

# `google.rpc.context.ProjectContext` and

2952

# `google.rpc.context.OriginContext`.

2953

#

2954

# Available context types are defined in package

2955

# `google.rpc.context`.

2956

"rules": [ # A list of RPC context rules that apply to individual API methods.

2957

#

2958

# **NOTE:** All service configuration rules follow "last one wins" order.

2959

{ # A context rule provides information about the context for an individual API

2960

# element.

2961

"provided": [ # A list of full type names of provided contexts.

2962

"A String",

2963

],

2964

"requested": [ # A list of full type names of requested contexts.

2965

"A String",

2966

],

2967

"selector": "A String", # Selects the methods to which this rule applies.

2968

#

2969

# Refer to selector for syntax details.

2970

},

2971

],

2972

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2973

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2974

# with the same name as the service is automatically generated to service all

2975

# defined APIs.

2976

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2977

# A service may expose any number of endpoints, and all endpoints share the

2978

# same service configuration, such as quota configuration and monitoring

2979

# configuration.

2980

#

2981

# Example service configuration:

2982

#

2983

# name: library-example.googleapis.com

2984

# endpoints:

2985

# # Below entry makes 'google.example.library.v1.Library'

2986

# # API be served from endpoint address library-example.googleapis.com.

2987

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2988

# # it to decide whether the subsequent cross-origin request is

2989

# # allowed to proceed.

2990

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2991

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

2992

"allowCors": True or False, # Allowing

2993

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2994

# cross-domain traffic, would allow the backends served from this endpoint to

2995

# receive and respond to HTTP OPTIONS requests. The response will be used by

2996

# the browser to determine whether the subsequent cross-origin request is

2997

# allowed to proceed.

2998

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2999

# please specify multiple google.api.Endpoint for each of the intented

3000

# alias.

3001

#

3002

# Additional names that this endpoint will be hosted on.

3003

"A String",

3004

],

3005

"features": [ # The list of features enabled on this endpoint.

3006

"A String",

3007

],

3008

"name": "A String", # The canonical name of this endpoint.

3009

"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>

3019

<pre>Gets a service configuration (version) for a managed service.

3020

3021

Args:

3022

serviceName: string, The name of the service. See the [overview](/service-management/overview)

3023

for naming requirements. For example: `example.googleapis.com`. (required)

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3024

configId: string, The id of the service configuration resource. (required)

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3025

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3032

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3033

{ # `Service` is the root object of Google service configuration schema. It

3034

# describes basic information about a service, such as the name and the

3035

# title, and delegates other aspects to sub-sections. Each sub-section is

3036

# either a proto message or a repeated proto message that configures a

3037

# 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]

3042

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3043

# name: calendar.googleapis.com

3044

# title: Google Calendar API

3045

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3046

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3047

# authentication:

3048

# providers:

3049

# - id: google_calendar_auth

3050

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3051

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3052

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3053

# - selector: "*"

3054

# requirements:

3055

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3056

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

3057

# service controller handles features like abuse, quota, billing, logging,

3058

# monitoring, etc.

3059

"environment": "A String", # The service control environment to use. If empty, no control plane

3060

# feature (like quota and billing) will be enabled.

3061

},

3062

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

3063

# by the Service.monitoring and Service.logging configurations.

3064

{ # An object that describes the schema of a MonitoredResource object using a

3065

# type name and a set of labels. For example, the monitored resource

3066

# descriptor for Google Compute Engine VM instances has a type of

3067

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

3068

# `"zone"` to identify particular VM instances.

3069

#

3070

# Different APIs can support different monitored resource types. APIs generally

3071

# provide a `list` method that returns the monitored resource descriptors used

3072

# by the API.

3073

"type": "A String", # Required. The monitored resource type. For example, the type

3074

# `"cloudsql_database"` represents databases in Google Cloud SQL.

3075

# The maximum length of this value is 256 characters.

3076

"labels": [ # Required. A set of labels used to describe instances of this monitored

3077

# resource type. For example, an individual Google Cloud SQL database is

3078

# identified by values for the labels `"database_id"` and `"zone"`.

3079

{ # A description of a label.

3080

"valueType": "A String", # The type of data that can be assigned to the label.

3081

"description": "A String", # A human-readable description for the label.

3082

"key": "A String", # The label key.

3083

},

3084

],

3085

"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]

3086

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

3087

# without any article or other determiners. For example,

3088

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3089

"description": "A String", # Optional. A detailed description of the monitored resource type that might

3090

# be used in documentation.

3091

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

3092

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

3093

# {type} is the value of the `type` field in this object and

3094

# {project_id} is a project ID that provides API-specific context for

3095

# accessing the type. APIs that do not use project information can use the

3096

# resource name format `"monitoredResourceDescriptors/{type}"`.

3097

},

3098

],

3099

"logs": [ # Defines the logs used by this service.

3100

{ # A description of a log type. Example in YAML format:

3101

#

3102

# - name: library.googleapis.com/activity_history

3103

# description: The history of borrowing and returning library items.

3104

# display_name: Activity

3105

# labels:

3106

# - key: /customer_id

3107

# description: Identifier of a library customer

3108

"labels": [ # The set of labels that are available to describe a specific log entry.

3109

# Runtime requests that contain labels not specified here are

3110

# considered invalid.

3111

{ # A description of a label.

3112

"valueType": "A String", # The type of data that can be assigned to the label.

3113

"description": "A String", # A human-readable description for the label.

3114

"key": "A String", # The label key.

3115

},

3116

],

3117

"displayName": "A String", # The human-readable name for this log. This information appears on

3118

# the user interface and should be concise.

3119

"description": "A String", # A human-readable description of this log. This information appears in

3120

# the documentation and can contain details.

3121

"name": "A String", # The name of the log. It must be less than 512 characters long and can

3122

# include the following characters: upper- and lower-case alphanumeric

3123

# characters [A-Za-z0-9], and punctuation characters including

3124

# slash, underscore, hyphen, period [/_-.].

3125

},

3126

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3127

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3128

#

3129

# A system parameter is a special kind of parameter defined by the API

3130

# system, not by an individual API. It is typically mapped to an HTTP header

3131

# and/or a URL query parameter. This configuration specifies which methods

3132

# change the names of the system parameters.

3133

"rules": [ # Define system parameters.

3134

#

3135

# The parameters defined here will override the default parameters

3136

# implemented by the system. If this field is missing from the service

3137

# config, default system parameters will be used. Default system parameters

3138

# and names is implementation-dependent.

3139

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3140

# Example: define api key for all methods

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3141

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

3148

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3149

#

3150

# Example: define 2 api key names for a specific method.

3151

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3152

# system_parameters

3153

# rules:

3154

# - selector: "/ListShelves"

3155

# parameters:

3156

# - name: api_key

3157

# http_header: Api-Key1

3158

# - name: api_key

3159

# http_header: Api-Key2

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3160

#

3161

# **NOTE:** All service configuration rules follow "last one wins" order.

3162

{ # Define a system parameter rule mapping system parameter definitions to

3163

# methods.

3164

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

3165

# For a given method call, only one of them should be used. If multiple

3166

# names are used the behavior is implementation-dependent.

3167

# If none of the specified names are present the behavior is

3168

# parameter-dependent.

3169

{ # Define a parameter's name and location. The parameter may be passed as either

3170

# an HTTP header or a URL query parameter, and if both are passed the behavior

3171

# is implementation-dependent.

3172

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

3173

# sensitive.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3174

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3175

"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

3180

# methods in all APIs.

3181

#

3182

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

3187

"rules": [ # A list of API backend rules that apply to individual API methods.

3188

#

3189

# **NOTE:** All service configuration rules follow "last one wins" order.

3190

{ # A backend rule provides configuration for an individual API element.

3191

"selector": "A String", # Selects the methods to which this rule applies.

3192

#

3193

# Refer to selector for syntax details.

3194

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

3195

# default depends on the deployment context.

3196

"address": "A String", # The address of the API backend.

3197

},

3198

],

3199

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3200

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3201

#

3202

# The example below shows how to configure monitored resources and metrics

3203

# for monitoring. In the example, a monitored resource and two metrics are

3204

# defined. The `library.googleapis.com/book/returned_count` metric is sent

3205

# to both producer and consumer projects, whereas the

3206

# `library.googleapis.com/book/overdue_count` metric is only sent to the

3207

# consumer project.

3208

#

3209

# monitored_resources:

3210

# - type: library.googleapis.com/branch

3211

# labels:

3212

# - key: /city

3213

# description: The city where the library branch is located in.

3214

# - key: /name

3215

# description: The name of the branch.

3216

# metrics:

3217

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

3222

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

3227

# monitoring:

3228

# producer_destinations:

3229

# - monitored_resource: library.googleapis.com/branch

3230

# metrics:

3231

# - library.googleapis.com/book/returned_count

3232

# consumer_destinations:

3233

# - monitored_resource: library.googleapis.com/branch

3234

# metrics:

3235

# - library.googleapis.com/book/returned_count

3236

# - library.googleapis.com/book/overdue_count

3237

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

3238

# There can be multiple producer destinations, each one must have a

3239

# different monitored resource type. A metric can be used in at most

3240

# one producer destination.

3241

{ # Configuration of a specific monitoring destination (the producer project

3242

# or the consumer project).

3243

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3244

# Service.monitored_resources section.

3245

"metrics": [ # Names of the metrics to report to this monitoring destination.

3246

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

3252

# There can be multiple consumer destinations, each one must have a

3253

# different monitored resource type. A metric can be used in at most

3254

# one consumer destination.

3255

{ # Configuration of a specific monitoring destination (the producer project

3256

# or the consumer project).

3257

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

3258

# Service.monitored_resources section.

3259

"metrics": [ # Names of the metrics to report to this monitoring destination.

3260

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

3267

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

3268

# by the client for tracking purpose. If empty, the server may choose to

3269

# generate one instead.

3270

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

3271

#

3272

# Example for an API targeted for external use:

3273

#

3274

# name: calendar.googleapis.com

3275

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3276

# providers:

3277

# - id: google_calendar_auth

3278

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

3279

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3280

# rules:

3281

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3282

# requirements:

3283

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3284

"rules": [ # A list of authentication rules that apply to individual API methods.

3285

#

3286

# **NOTE:** All service configuration rules follow "last one wins" order.

3287

{ # Authentication rules for the service.

3288

#

3289

# By default, if a method has any authentication requirements, every request

3290

# must include a valid credential matching one of the requirements.

3291

# It's an error to include more than one kind of credential in a single

3292

# request.

3293

#

3294

# If a method doesn't have any auth requirements, request credentials will be

3295

# ignored.

3296

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

3297

# there are scopes defined for "Read-only access to Google Calendar" and

3298

# "Access to Cloud Platform". Users can consent to a scope for an application,

3299

# giving it permission to access that data on their behalf.

3300

#

3301

# OAuth scope specifications should be fairly coarse grained; a user will need

3302

# to see and understand the text description of what your scope means.

3303

#

3304

# In most cases: use one or at most two OAuth scopes for an entire family of

3305

# products. If your product has multiple APIs, you should probably be sharing

3306

# the OAuth scope across all of those APIs.

3307

#

3308

# When you need finer grained OAuth consent screens: talk with your product

3309

# management about how developers will use them in practice.

3310

#

3311

# Please note that even though each of the canonical scopes is enough for a

3312

# request to be accepted and passed to the backend, a request can still fail

3313

# due to the backend requiring additional scopes or permissions.

3314

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

3315

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

3320

# https://www.googleapis.com/auth/calendar.read

3321

},

3322

"requirements": [ # Requirements for additional authentication providers.

3323

{ # User-defined authentication requirements, including support for

3324

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3325

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3330

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

3331

# implemented and accepted in all the runtime components.

3332

#

3333

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3334

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3335

# that are allowed to access. A JWT containing any of these audiences will

3336

# be accepted. When this setting is absent, only JWTs with audience

3337

# "https://Service_name/API_name"

3338

# will be accepted. For example, if no audiences are in the setting,

3339

# LibraryService API will only accept JWTs with the following audience

3340

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3345

# bookstore_web.apps.googleusercontent.com

3346

},

3347

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

3348

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

3349

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

3350

#

3351

# For requests without credentials, if the service control environment is

3352

# specified, each incoming request **must** be associated with a service

3353

# consumer. This can be done by passing an API key that belongs to a consumer

3354

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3355

"selector": "A String", # Selects the methods to which this rule applies.

3356

#

3357

# Refer to selector for syntax details.

3358

},

3359

],

3360

"providers": [ # Defines a set of authentication providers that a service supports.

3361

{ # Configuration for an anthentication provider, including support for

3362

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

3363

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

3364

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

3365

# Optional if the key set document:

3366

# - can be retrieved from

3367

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

3368

# of the issuer.

3369

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

3370

#

3371

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3372

"audiences": "A String", # The list of JWT

3373

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

3374

# that are allowed to access. A JWT containing any of these audiences will

3375

# be accepted. When this setting is absent, only JWTs with audience

3376

# "https://Service_name/API_name"

3377

# will be accepted. For example, if no audiences are in the setting,

3378

# LibraryService API will only accept JWTs with the following audience

3379

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

3384

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3385

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

3386

# `AuthRequirement.provider_id`.

3387

#

3388

# Example: "bookstore_auth".

3389

"issuer": "A String", # Identifies the principal that issued the JWT. See

3390

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

3391

# Usually a URL or an email address.

3392

#

3393

# Example: https://securetoken.google.com

3394

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

3399

"rules": [ # A list of usage rules that apply to individual API methods.

3400

#

3401

# **NOTE:** All service configuration rules follow "last one wins" order.

3402

{ # Usage configuration rules for the service.

3403

#

3404

# NOTE: Under development.

3405

#

3406

#

3407

# Use this rule to configure unregistered calls for the service. Unregistered

3408

# calls are calls that do not contain consumer project identity.

3409

# (Example: calls that do not contain an API key).

3410

# By default, API methods do not allow unregistered calls, and each method call

3411

# must be identified by a consumer project identity. Use this rule to

3412

# allow/disallow unregistered calls.

3413

#

3414

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

3420

#

3421

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

3426

# allow_unregistered_calls: true

3427

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

3428

# methods in all APIs.

3429

#

3430

# Refer to selector for syntax details.

3431

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

3432

},

3433

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3434

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

3435

# service producer.

3436

#

3437

# Google Service Management currently only supports

3438

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

3439

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

3440

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

3441

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3442

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

3443

# service. Each requirement is of the form <service.name>/<requirement-id>;

3444

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

3449

# influence interpretation of the configuration, for example, to

3450

# determine defaults. This is documented together with applicable

3451

# options. The current default for the config version itself is `3`.

3452

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

3453

# Members of this project can manage the service configuration,

3454

# manage consumption of the service, etc.

3455

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

3456

# HttpRule, each specifying the mapping of an RPC method

3457

# to one or more HTTP REST API methods.

3458

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

3459

#

3460

# **NOTE:** All service configuration rules follow "last one wins" order.

3461

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

3462

# REST APIs. The mapping determines what portions of the request

3463

# message are populated from the path, query parameters, or body of

3464

# the HTTP request. The mapping is typically specified as an

3465

# `google.api.http` annotation, see "google/api/annotations.proto"

3466

# for details.

3467

#

3468

# The mapping consists of a field specifying the path template and

3469

# method kind. The path template can refer to fields in the request

3470

# message, as in the example below which describes a REST GET

3471

# operation on a resource collection of messages:

3472

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3473

#

3474

# service Messaging {

3475

# rpc GetMessage(GetMessageRequest) returns (Message) {

3476

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

3477

# }

3478

# }

3479

# message GetMessageRequest {

3480

# message SubMessage {

3481

# string subfield = 1;

3482

# }

3483

# string message_id = 1; // mapped to the URL

3484

# SubMessage sub = 2; // `sub.subfield` is url-mapped

3485

# }

3486

# message Message {

3487

# string text = 1; // content of the resource

3488

# }

3489

#

3490

# The same http annotation can alternatively be expressed inside the

3491

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

3496

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3497

#

3498

# This definition enables an automatic, bidrectional mapping of HTTP

3499

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

3504

#

3505

# In general, not only fields but also field paths can be referenced

3506

# from a path pattern. Fields mapped to the path pattern cannot be

3507

# repeated and must have a primitive (non-message) type.

3508

#

3509

# Any fields in the request message which are not bound by the path

3510

# pattern automatically become (optional) HTTP query

3511

# parameters. Assume the following definition of the request message:

3512

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3513

#

3514

# message GetMessageRequest {

3515

# message SubMessage {

3516

# string subfield = 1;

3517

# }

3518

# string message_id = 1; // mapped to the URL

3519

# int64 revision = 2; // becomes a parameter

3520

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

3521

# }

3522

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3523

#

3524

# 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"))`

3529

#

3530

# Note that fields which are mapped to HTTP parameters must have a

3531

# primitive type or a repeated primitive type. Message types are not

3532

# allowed. In the case of a repeated type, the parameter can be

3533

# repeated in the URL, as in `...?param=A&param=B`.

3534

#

3535

# For HTTP method kinds which allow a request body, the `body` field

3536

# specifies the mapping. Consider a REST update method on the

3537

# message resource collection:

3538

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3539

#

3540

# service Messaging {

3541

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

3542

# option (google.api.http) = {

3543

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

3549

# string message_id = 1; // mapped to the URL

3550

# Message message = 2; // mapped to the body

3551

# }

3552

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3553

#

3554

# The following HTTP JSON to RPC mapping is enabled, where the

3555

# representation of the JSON in the request body is determined by

3556

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

3561

#

3562

# The special name `*` can be used in the body mapping to define that

3563

# every field not bound by the path template should be mapped to the

3564

# request body. This enables the following alternative definition of

3565

# the update method:

3566

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3567

# service Messaging {

3568

# rpc UpdateMessage(Message) returns (Message) {

3569

# option (google.api.http) = {

3570

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

3577

# string text = 2;

3578

# }

3579

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3580

#

3581

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

3586

#

3587

# Note that when using `*` in the body mapping, it is not possible to

3588

# have HTTP parameters, as all fields not bound by the path end in

3589

# the body. This makes this option more rarely used in practice of

3590

# defining REST APIs. The common usage of `*` is in custom methods

3591

# which don't use the URL at all for transferring data.

3592

#

3593

# It is possible to define multiple HTTP methods for one RPC by using

3594

# the `additional_bindings` option. Example:

3595

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

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}"

3602

# }

3603

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3604

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3605

# }

3606

# message GetMessageRequest {

3607

# string message_id = 1;

3608

# string user_id = 2;

3609

# }

3610

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3611

#

3612

# 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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3651

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

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

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3670

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

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.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3727

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3728

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3729

# For custom options, it should be the fully-qualified name. For example,

3730

# `"google.api.http"`.

3731

"value": { # The option's value packed in an Any message. If the value is a primitive,

3732

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3733

# should be used. If the value is an enum, it should be stored as an int32

3734

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3735

"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

3742

# message.

3743

# protobuf element, like the file in which it is defined.

3744

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

3745

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

3746

},

3747

"mixins": [ # Included APIs. See Mixin.

3748

{ # Declares an API to be included in this API. The including API must

3749

# redeclare all the methods from the included API, but documentation

3750

# and options are inherited as follows:

3751

#

3752

# - If after comment and whitespace stripping, the documentation

3753

# string of the redeclared method is empty, it will be inherited

3754

# from the original method.

3755

#

3756

# - Each annotation belonging to the service config (http,

3757

# visibility) which is not set in the redeclared method will be

3758

# inherited.

3759

#

3760

# - If an http annotation is inherited, the path pattern will be

3761

# modified as follows. Any version prefix will be replaced by the

3762

# version of the including API plus the root path if specified.

3763

#

3764

# Example of a simple mixin:

3765

#

3766

# package google.acl.v1;

3767

# service AccessControl {

3768

# // Get the underlying ACL object.

3769

# rpc GetAcl(GetAclRequest) returns (Acl) {

3770

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

3775

# service Storage {

3776

# // rpc GetAcl(GetAclRequest) returns (Acl);

3777

#

3778

# // Get a data record.

3779

# rpc GetData(GetDataRequest) returns (Data) {

3780

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

3785

#

3786

# apis:

3787

# - name: google.storage.v2.Storage

3788

# mixins:

3789

# - name: google.acl.v1.AccessControl

3790

#

3791

# The mixin construct implies that all methods in `AccessControl` are

3792

# also declared with same name and request/response types in

3793

# `Storage`. A documentation generator or annotation processor will

3794

# see the effective `Storage.GetAcl` method after inherting

3795

# documentation and annotations as follows:

3796

#

3797

# service Storage {

3798

# // Get the underlying ACL object.

3799

# rpc GetAcl(GetAclRequest) returns (Acl) {

3800

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

3806

#

3807

# If the `root` field in the mixin is specified, it should be a

3808

# relative path under which inherited HTTP paths are placed. Example:

3809

#

3810

# apis:

3811

# - name: google.storage.v2.Storage

3812

# mixins:

3813

# - name: google.acl.v1.AccessControl

3814

# root: acls

3815

#

3816

# This implies the following inherited HTTP annotation:

3817

#

3818

# service Storage {

3819

# // Get the underlying ACL object.

3820

# rpc GetAcl(GetAclRequest) returns (Acl) {

3821

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

3826

# are rooted.

3827

"name": "A String", # The fully qualified name of the API which is included.

3828

},

3829

],

3830

"syntax": "A String", # The source syntax of the service.

3831

"version": "A String", # A version string for this api. If specified, must have the form

3832

# `major-version.minor-version`, as in `1.10`. If the minor version

3833

# is omitted, it defaults to zero. If the entire version field is

3834

# empty, the major version is derived from the package name, as

3835

# outlined below. If the field is not empty, the version in the

3836

# package name will be verified to be consistent with what is

3837

# provided here.

3838

#

3839

# The versioning schema uses [semantic

3840

# versioning](http://semver.org) where the major version number

3841

# indicates a breaking change and the minor version an additive,

3842

# non-breaking change. Both version numbers are signals to users

3843

# what to expect from different versions, and should be carefully

3844

# chosen based on the product plan.

3845

#

3846

# The major version is also reflected in the package name of the

3847

# API, which must end in `v<major-version>`, as in

3848

# `google.feature.v1`. For major versions 0 and 1, the suffix can

3849

# be omitted. Zero major versions must only be used for

3850

# experimental, none-GA apis.

3851

"options": [ # Any metadata attached to the API.

3852

{ # A protocol buffer option, which can be attached to a message, field,

3853

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3854

"name": "A String", # The option's name. For protobuf built-in options (options defined in

3855

# descriptor.proto), this is the short name. For example, `"map_entry"`.

3856

# For custom options, it should be the fully-qualified name. For example,

3857

# `"google.api.http"`.

3858

"value": { # The option's value packed in an Any message. If the value is a primitive,

3859

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

3860

# should be used. If the value is an enum, it should be stored as an int32

3861

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3862

"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

3867

# followed by the api's simple name.

3868

},

3869

],

3870

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

3871

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

3879

# - google.foo.v1.AnotherError

3880

"rules": [ # The list of custom error rules that apply to individual API messages.

3881

#

3882

# **NOTE:** All service configuration rules follow "last one wins" order.

3883

{ # A custom error rule.

3884

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

3885

# objects of this type will be filtered when they appear in error payload.

3886

"selector": "A String", # Selects messages to which this rule applies.

3887

#

3888

# Refer to selector for syntax details.

3889

},

3890

],

3891

"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.

3896

# elements. Restrictions are specified using visibility labels

3897

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

3898

#

3899

# Users and projects can have access to more than one visibility label. The

3900

# effective visibility for multiple labels is the union of each label's

3901

# elements, plus any unrestricted elements.

3902

#

3903

# If an element and its parents have no restrictions, visibility is

3904

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3911

# restriction: TRUSTED_TESTER

3912

# - selector: google.calendar.Calendar.Delegate

3913

# restriction: GOOGLE_INTERNAL

3914

#

3915

# Here, all methods are publicly visible except for the restricted methods

3916

# EnhancedSearch and Delegate.

3917

"rules": [ # A list of visibility rules that apply to individual API elements.

3918

#

3919

# **NOTE:** All service configuration rules follow "last one wins" order.

3920

{ # A visibility rule provides visibility configuration for an individual API

3921

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

3922

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

3923

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3924

#

3925

# If a rule has multiple labels, removing one of the labels but not all of

3926

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

3933

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

3934

#

3935

# Removing GOOGLE_INTERNAL from this restriction will break clients that

3936

# rely on this method and only had access to it through GOOGLE_INTERNAL.

3937

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

3938

#

3939

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3944

{ # Defines a metric type and its schema. Once a metric descriptor is created,

3945

# deleting or altering it stops data collection and makes the metric type's

3946

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3947

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

3948

# Use sentence case without an ending period, for example "Request count".

3949

"description": "A String", # A detailed description of the metric, which can be used in documentation.

3950

"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]

3951

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3952

"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]

3953

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3954

"labels": [ # The set of labels that can be used to describe a specific

3955

# instance of this metric type. For example, the

3956

# `appengine.googleapis.com/http/server/response_latencies` metric

3957

# type has a label for the HTTP response code, `response_code`, so

3958

# you can look at latencies for successful responses or just

3959

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3960

{ # A description of a label.

3961

"valueType": "A String", # The type of data that can be assigned to the label.

3962

"description": "A String", # A human-readable description for the label.

3963

"key": "A String", # The label key.

3964

},

3965

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3966

"type": "A String", # The metric type, including its DNS name prefix. The type is not

3967

# URL-encoded. All user-defined metric types have the DNS name

3968

# `custom.googleapis.com`. Metric types should use a natural hierarchical

3969

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3970

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

3971

# "custom.googleapis.com/invoice/paid/amount"

3972

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

3973

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

3974

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

3975

# supported units are a subset of [The Unified Code for Units of

3976

# Measure](http://unitsofmeasure.org/ucum.html) standard:

3977

#

3978

# **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)

3993

# * `P` peta (10**15)

3994

# * `E` exa (10**18)

3995

# * `Z` zetta (10**21)

3996

# * `Y` yotta (10**24)

3997

# * `m` milli (10**-3)

3998

# * `u` micro (10**-6)

3999

# * `n` nano (10**-9)

4000

# * `p` pico (10**-12)

4001

# * `f` femto (10**-15)

4002

# * `a` atto (10**-18)

4003

# * `z` zepto (10**-21)

4004

# * `y` yocto (10**-24)

4005

# * `Ki` kibi (2**10)

4006

# * `Mi` mebi (2**20)

4007

# * `Gi` gibi (2**30)

4008

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

4013

#

4014

# The grammar also includes these connectors:

4015

#

4016

# * `/` division (as an infix operator, e.g. `1/s`).

4017

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

4018

#

4019

# The grammar for a unit is as follows:

4020

#

4021

# Expression = Component { "." Component } { "/" Component } ;

4022

#

4023

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

4033

# equivalent to `1` if it is used alone. For examples,

4034

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

4035

# * `NAME` is a sequence of non-blank printable ASCII characters not

4036

# containing '{' or '}'.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4037

"name": "A String", # The resource name of the metric descriptor. Depending on the

4038

# implementation, the name typically includes: (1) the parent resource name

4039

# that defines the scope of the metric type or of its data; and (2) the

4040

# metric's URL-encoded type, which also appears in the `type` field of this

4041

# descriptor. For example, following is the resource name of a custom

4042

# metric within the GCP project 123456789:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4043

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4044

# "projects/123456789/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4045

},

4046

],

4047

"enums": [ # A list of all enum types included in this API service. Enums

4048

# referenced directly or indirectly by the `apis` are automatically

4049

# included. Enums which are not referenced but shall be included

4050

# should be listed here by name. Example:

4051

#

4052

# enums:

4053

# - name: google.someapi.v1.SomeEnum

4054

{ # Enum type definition.

4055

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4056

# protobuf element, like the file in which it is defined.

4057

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4058

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4059

},

4060

"enumvalue": [ # Enum value definitions.

4061

{ # Enum value definition.

4062

"number": 42, # Enum value number.

4063

"options": [ # Protocol buffer options.

4064

{ # A protocol buffer option, which can be attached to a message, field,

4065

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4066

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4067

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4068

# For custom options, it should be the fully-qualified name. For example,

4069

# `"google.api.http"`.

4070

"value": { # The option's value packed in an Any message. If the value is a primitive,

4071

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4072

# should be used. If the value is an enum, it should be stored as an int32

4073

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4074

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

4079

},

4080

],

4081

"options": [ # Protocol buffer options.

4082

{ # A protocol buffer option, which can be attached to a message, field,

4083

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4084

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4085

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4086

# For custom options, it should be the fully-qualified name. For example,

4087

# `"google.api.http"`.

4088

"value": { # The option's value packed in an Any message. If the value is a primitive,

4089

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4090

# should be used. If the value is an enum, it should be stored as an int32

4091

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4092

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

4097

"syntax": "A String", # The source syntax.

4098

},

4099

],

4100

"types": [ # A list of all proto message types included in this API service.

4101

# Types referenced directly or indirectly by the `apis` are

4102

# automatically included. Messages which are not referenced but

4103

# shall be included, such as types used by the `google.protobuf.Any` type,

4104

# should be listed here by name. Example:

4105

#

4106

# types:

4107

# - name: google.protobuf.Int32

4108

{ # A protocol buffer message type.

4109

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4110

"A String",

4111

],

4112

"name": "A String", # The fully qualified message name.

4113

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4114

# protobuf element, like the file in which it is defined.

4115

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4116

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4117

},

4118

"syntax": "A String", # The source syntax.

4119

"fields": [ # The list of fields.

4120

{ # A single field of a message type.

4121

"kind": "A String", # The field type.

4122

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4123

# types. The first type has index 1; zero means the type is not in the list.

4124

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4125

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4126

"name": "A String", # The field name.

4127

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4128

"jsonName": "A String", # The field JSON name.

4129

"number": 42, # The field number.

4130

"cardinality": "A String", # The field cardinality.

4131

"options": [ # The protocol buffer options.

4132

{ # A protocol buffer option, which can be attached to a message, field,

4133

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4134

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4135

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4136

# For custom options, it should be the fully-qualified name. For example,

4137

# `"google.api.http"`.

4138

"value": { # The option's value packed in an Any message. If the value is a primitive,

4139

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4140

# should be used. If the value is an enum, it should be stored as an int32

4141

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4142

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4147

},

4148

],

4149

"options": [ # The protocol buffer options.

4150

{ # A protocol buffer option, which can be attached to a message, field,

4151

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4152

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4153

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4154

# For custom options, it should be the fully-qualified name. For example,

4155

# `"google.api.http"`.

4156

"value": { # The option's value packed in an Any message. If the value is a primitive,

4157

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4158

# should be used. If the value is an enum, it should be stored as an int32

4159

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4160

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4166

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4167

#

4168

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4169

# producer and consumer projects. In the example, the `activity_history`

4170

# log is sent to both the producer and consumer projects, whereas the

4171

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4172

#

4173

# monitored_resources:

4174

# - type: library.googleapis.com/branch

4175

# labels:

4176

# - key: /city

4177

# description: The city where the library branch is located in.

4178

# - key: /name

4179

# description: The name of the branch.

4180

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4181

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4182

# labels:

4183

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4184

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4185

# logging:

4186

# producer_destinations:

4187

# - monitored_resource: library.googleapis.com/branch

4188

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4189

# - activity_history

4190

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4191

# consumer_destinations:

4192

# - monitored_resource: library.googleapis.com/branch

4193

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4194

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4195

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

4196

# There can be multiple producer destinations, each one must have a

4197

# different monitored resource type. A log can be used in at most

4198

# one producer destination.

4199

{ # Configuration of a specific logging destination (the producer project

4200

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4201

"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]

4202

# Service.monitored_resources section.

4203

"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]

4204

# be defined in the Service.logs section. If the log name is

4205

# not a domain scoped name, it will be automatically prefixed with

4206

# 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.

4212

# There can be multiple consumer destinations, each one must have a

4213

# different monitored resource type. A log can be used in at most

4214

# one consumer destination.

4215

{ # Configuration of a specific logging destination (the producer project

4216

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

4217

"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]

4218

# Service.monitored_resources section.

4219

"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]

4220

# be defined in the Service.logs section. If the log name is

4221

# not a domain scoped name, it will be automatically prefixed with

4222

# 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,

4229

# e.g. `calendar.googleapis.com`.

4230

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

4231

#

4232

# Example:

4233

# <pre><code>documentation:

4234

# summary: >

4235

# The Google Calendar API gives access

4236

# to most calendar features.

4237

# pages:

4238

# - name: Overview

4239

# content: (== include google/foo/overview.md ==)

4240

# - name: Tutorial

4241

# content: (== include google/foo/tutorial.md ==)

4242

# subpages;

4243

# - name: Java

4244

# content: (== include google/foo/tutorial_java.md ==)

4245

# rules:

4246

# - selector: google.calendar.Calendar.Get

4247

# description: >

4248

# ...

4249

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

4254

# standard markdown features, definition lists, tables and fenced

4255

# code blocks are supported. Section headers can be provided and are

4256

# interpreted relative to the section nesting of the context where

4257

# a documentation fragment is embedded.

4258

#

4259

# Documentation from the IDL is merged with documentation defined

4260

# via the config at normalization time, where documentation provided

4261

# by config rules overrides IDL provided.

4262

#

4263

# A number of constructs specific to the API platform are supported

4264

# in documentation text.

4265

#

4266

# In order to reference a proto element, the following

4267

# notation can be used:

4268

# <pre><code>[fully.qualified.proto.name][]</code></pre>

4269

# To override the display text used for the link, this can be used:

4270

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

4271

# Text can be excluded from doc using the following notation:

4272

# <pre><code>(-- internal comment --)</code></pre>

4273

# Comments can be made conditional using a visibility label. The below

4274

# text will be only rendered if the `BETA` label is available:

4275

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

4276

# A few directives are available in documentation. Note that

4277

# directives must appear on a single line to be properly

4278

# identified. The `include` directive includes a markdown file from

4279

# an external source:

4280

# <pre><code>(== include path/to/file ==)</code></pre>

4281

# The `resource_for` directive marks a message to be the resource of

4282

# a collection in REST view. If it is not specified, tools attempt

4283

# to infer the resource from the operations in a collection:

4284

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

4285

# The directive `suppress_warning` does not directly affect documentation

4286

# and is documented together with service config validation.

4287

"rules": [ # A list of documentation rules that apply to individual API elements.

4288

#

4289

# **NOTE:** All service configuration rules follow "last one wins" order.

4290

{ # A documentation rule provides information about individual API elements.

4291

"description": "A String", # Description of the selected API(s).

4292

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

4293

# element is marked as `deprecated`.

4294

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

4295

# qualified name of the element which may end in "*", indicating a wildcard.

4296

# Wildcards are only allowed at the end and for a whole component of the

4297

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

4298

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

4303

# <pre><code>documentation:

4304

# summary: ...

4305

# overview: (== include overview.md ==)

4306

# </code></pre>

4307

# This is a shortcut for the following declaration (using pages style):

4308

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

4313

# </code></pre>

4314

# Note: you cannot specify both `overview` field and `pages` field.

4315

"summary": "A String", # A short summary of what the service does. Can only be provided by

4316

# plain text.

4317

"pages": [ # The top level pages for the documentation set.

4318

{ # Represents a documentation page. A page can contain subpages to represent

4319

# nested documentation set structure.

4320

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

4321

# to include content from a Markdown file.

4322

"subpages": [ # Subpages of this page. The order of subpages specified here will be

4323

# honored in the generated docset.

4324

# Object with schema name: Page

4325

],

4326

"name": "A String", # The name of the page. It will be used as an identity of the page to

4327

# generate URI of the page, text of the link to this page in navigation,

4328

# etc. The full page name (start from the root page name to this page

4329

# concatenated with `.`) can be used as reference to the page in your

4330

# documentation. For example:

4331

# <pre><code>pages:

4332

# - name: Tutorial

4333

# content: (== include tutorial.md ==)

4334

# subpages:

4335

# - name: Java

4336

# content: (== include tutorial_java.md ==)

4337

# </code></pre>

4338

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

4343

},

4344

"systemTypes": [ # A list of all proto message types included in this API service.

4345

# It serves similar purpose as [google.api.Service.types], except that

4346

# these types are not needed by user-defined APIs. Therefore, they will not

4347

# show up in the generated discovery doc. This field should only be used

4348

# to define system APIs in ESF.

4349

{ # A protocol buffer message type.

4350

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

4351

"A String",

4352

],

4353

"name": "A String", # The fully qualified message name.

4354

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

4355

# protobuf element, like the file in which it is defined.

4356

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

4357

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

4358

},

4359

"syntax": "A String", # The source syntax.

4360

"fields": [ # The list of fields.

4361

{ # A single field of a message type.

4362

"kind": "A String", # The field type.

4363

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

4364

# types. The first type has index 1; zero means the type is not in the list.

4365

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

4366

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

4367

"name": "A String", # The field name.

4368

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

4369

"jsonName": "A String", # The field JSON name.

4370

"number": 42, # The field number.

4371

"cardinality": "A String", # The field cardinality.

4372

"options": [ # The protocol buffer options.

4373

{ # A protocol buffer option, which can be attached to a message, field,

4374

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4375

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4376

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4377

# For custom options, it should be the fully-qualified name. For example,

4378

# `"google.api.http"`.

4379

"value": { # The option's value packed in an Any message. If the value is a primitive,

4380

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4381

# should be used. If the value is an enum, it should be stored as an int32

4382

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4383

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

4388

},

4389

],

4390

"options": [ # The protocol buffer options.

4391

{ # A protocol buffer option, which can be attached to a message, field,

4392

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4393

"name": "A String", # The option's name. For protobuf built-in options (options defined in

4394

# descriptor.proto), this is the short name. For example, `"map_entry"`.

4395

# For custom options, it should be the fully-qualified name. For example,

4396

# `"google.api.http"`.

4397

"value": { # The option's value packed in an Any message. If the value is a primitive,

4398

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

4399

# should be used. If the value is an enum, it should be stored as an int32

4400

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4401

"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

4416

# - google.rpc.context.OriginContext

4417

#

4418

# The above specifies that all methods in the API request

4419

# `google.rpc.context.ProjectContext` and

4420

# `google.rpc.context.OriginContext`.

4421

#

4422

# Available context types are defined in package

4423

# `google.rpc.context`.

4424

"rules": [ # A list of RPC context rules that apply to individual API methods.

4425

#

4426

# **NOTE:** All service configuration rules follow "last one wins" order.

4427

{ # A context rule provides information about the context for an individual API

4428

# element.

4429

"provided": [ # A list of full type names of provided contexts.

4430

"A String",

4431

],

4432

"requested": [ # A list of full type names of requested contexts.

4433

"A String",

4434

],

4435

"selector": "A String", # Selects the methods to which this rule applies.

4436

#

4437

# Refer to selector for syntax details.

4438

},

4439

],

4440

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4441

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

4442

# with the same name as the service is automatically generated to service all

4443

# defined APIs.

4444

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

4445

# A service may expose any number of endpoints, and all endpoints share the

4446

# same service configuration, such as quota configuration and monitoring

4447

# configuration.

4448

#

4449

# Example service configuration:

4450

#

4451

# name: library-example.googleapis.com

4452

# endpoints:

4453

# # Below entry makes 'google.example.library.v1.Library'

4454

# # API be served from endpoint address library-example.googleapis.com.

4455

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

4456

# # it to decide whether the subsequent cross-origin request is

4457

# # allowed to proceed.

4458

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4459

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4460

"allowCors": True or False, # Allowing

4461

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

4462

# cross-domain traffic, would allow the backends served from this endpoint to

4463

# receive and respond to HTTP OPTIONS requests. The response will be used by

4464

# the browser to determine whether the subsequent cross-origin request is

4465

# allowed to proceed.

4466

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

4467

# please specify multiple google.api.Endpoint for each of the intented

4468

# alias.

4469

#

4470

# Additional names that this endpoint will be hosted on.

4471

"A String",

4472

],

4473

"features": [ # The list of features enabled on this endpoint.

4474

"A String",

4475

],

4476

"name": "A String", # The canonical name of this endpoint.

4477

"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>

4487

<pre>Lists the history of the service configuration for a managed service,

4488

from the newest to the oldest.

4489

4490

Args:

4491

serviceName: string, The name of the service. See the [overview](/service-management/overview)

4492

for naming requirements. For example: `example.googleapis.com`. (required)

4493

pageSize: integer, The max number of items to include in the response list.

4494

pageToken: string, The token of the page to retrieve.

4495

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4502

4503

{ # Response message for ListServiceConfigs method.

4504

"nextPageToken": "A String", # The token of the next page of results.

4505

"serviceConfigs": [ # The list of service configuration resources.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4506

{ # `Service` is the root object of Google service configuration schema. It

4507

# describes basic information about a service, such as the name and the

4508

# title, and delegates other aspects to sub-sections. Each sub-section is

4509

# either a proto message or a repeated proto message that configures a

4510

# 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]

4515

# config_version: 3

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4516

# name: calendar.googleapis.com

4517

# title: Google Calendar API

4518

# apis:

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4519

# - name: google.calendar.v3.Calendar

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4520

# authentication:

4521

# providers:

4522

# - id: google_calendar_auth

4523

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4524

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4525

# rules:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4526

# - selector: "*"

4527

# requirements:

4528

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4529

"control": { # Selects and configures the service controller used by the service. The # Configuration for the service control plane.

4530

# service controller handles features like abuse, quota, billing, logging,

4531

# monitoring, etc.

4532

"environment": "A String", # The service control environment to use. If empty, no control plane

4533

# feature (like quota and billing) will be enabled.

4534

},

4535

"monitoredResources": [ # Defines the monitored resources used by this service. This is required

4536

# by the Service.monitoring and Service.logging configurations.

4537

{ # An object that describes the schema of a MonitoredResource object using a

4538

# type name and a set of labels. For example, the monitored resource

4539

# descriptor for Google Compute Engine VM instances has a type of

4540

# `"gce_instance"` and specifies the use of the labels `"instance_id"` and

4541

# `"zone"` to identify particular VM instances.

4542

#

4543

# Different APIs can support different monitored resource types. APIs generally

4544

# provide a `list` method that returns the monitored resource descriptors used

4545

# by the API.

4546

"type": "A String", # Required. The monitored resource type. For example, the type

4547

# `"cloudsql_database"` represents databases in Google Cloud SQL.

4548

# The maximum length of this value is 256 characters.

4549

"labels": [ # Required. A set of labels used to describe instances of this monitored

4550

# resource type. For example, an individual Google Cloud SQL database is

4551

# identified by values for the labels `"database_id"` and `"zone"`.

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", # Optional. A concise name for the monitored resource type that might be

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

4559

# displayed in user interfaces. It should be a Title Cased Noun Phrase,

4560

# without any article or other determiners. For example,

4561

# `"Google Cloud SQL Database"`.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4562

"description": "A String", # Optional. A detailed description of the monitored resource type that might

4563

# be used in documentation.

4564

"name": "A String", # Optional. The resource name of the monitored resource descriptor:

4565

# `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where

4566

# {type} is the value of the `type` field in this object and

4567

# {project_id} is a project ID that provides API-specific context for

4568

# accessing the type. APIs that do not use project information can use the

4569

# resource name format `"monitoredResourceDescriptors/{type}"`.

4570

},

4571

],

4572

"logs": [ # Defines the logs used by this service.

4573

{ # A description of a log type. Example in YAML format:

4574

#

4575

# - name: library.googleapis.com/activity_history

4576

# description: The history of borrowing and returning library items.

4577

# display_name: Activity

4578

# labels:

4579

# - key: /customer_id

4580

# description: Identifier of a library customer

4581

"labels": [ # The set of labels that are available to describe a specific log entry.

4582

# Runtime requests that contain labels not specified here are

4583

# considered invalid.

4584

{ # A description of a label.

4585

"valueType": "A String", # The type of data that can be assigned to the label.

4586

"description": "A String", # A human-readable description for the label.

4587

"key": "A String", # The label key.

4588

},

4589

],

4590

"displayName": "A String", # The human-readable name for this log. This information appears on

4591

# the user interface and should be concise.

4592

"description": "A String", # A human-readable description of this log. This information appears in

4593

# the documentation and can contain details.

4594

"name": "A String", # The name of the log. It must be less than 512 characters long and can

4595

# include the following characters: upper- and lower-case alphanumeric

4596

# characters [A-Za-z0-9], and punctuation characters including

4597

# slash, underscore, hyphen, period [/_-.].

4598

},

4599

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4600

"systemParameters": { # ### System parameter configuration # System parameter configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4601

#

4602

# A system parameter is a special kind of parameter defined by the API

4603

# system, not by an individual API. It is typically mapped to an HTTP header

4604

# and/or a URL query parameter. This configuration specifies which methods

4605

# change the names of the system parameters.

4606

"rules": [ # Define system parameters.

4607

#

4608

# The parameters defined here will override the default parameters

4609

# implemented by the system. If this field is missing from the service

4610

# config, default system parameters will be used. Default system parameters

4611

# and names is implementation-dependent.

4612

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4613

# Example: define api key for all methods

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4614

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

4621

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4622

#

4623

# Example: define 2 api key names for a specific method.

4624

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4625

# system_parameters

4626

# rules:

4627

# - selector: "/ListShelves"

4628

# parameters:

4629

# - name: api_key

4630

# http_header: Api-Key1

4631

# - name: api_key

4632

# http_header: Api-Key2

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4633

#

4634

# **NOTE:** All service configuration rules follow "last one wins" order.

4635

{ # Define a system parameter rule mapping system parameter definitions to

4636

# methods.

4637

"parameters": [ # Define parameters. Multiple names may be defined for a parameter.

4638

# For a given method call, only one of them should be used. If multiple

4639

# names are used the behavior is implementation-dependent.

4640

# If none of the specified names are present the behavior is

4641

# parameter-dependent.

4642

{ # Define a parameter's name and location. The parameter may be passed as either

4643

# an HTTP header or a URL query parameter, and if both are passed the behavior

4644

# is implementation-dependent.

4645

"urlQueryParameter": "A String", # Define the URL query parameter name to use for the parameter. It is case

4646

# sensitive.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4647

"name": "A String", # Define the name of the parameter, such as "api_key" . It is case sensitive.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4648

"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

4653

# methods in all APIs.

4654

#

4655

# Refer to selector for syntax details.

},

],

},

"backend": { # `Backend` defines the backend configuration for a service. # API backend configuration.

4660

"rules": [ # A list of API backend rules that apply to individual API methods.

4661

#

4662

# **NOTE:** All service configuration rules follow "last one wins" order.

4663

{ # A backend rule provides configuration for an individual API element.

4664

"selector": "A String", # Selects the methods to which this rule applies.

4665

#

4666

# Refer to selector for syntax details.

4667

"deadline": 3.14, # The number of seconds to wait for a response from a request. The

4668

# default depends on the deployment context.

4669

"address": "A String", # The address of the API backend.

4670

},

4671

],

4672

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

4673

"monitoring": { # Monitoring configuration of the service. # Monitoring configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4674

#

4675

# The example below shows how to configure monitored resources and metrics

4676

# for monitoring. In the example, a monitored resource and two metrics are

4677

# defined. The `library.googleapis.com/book/returned_count` metric is sent

4678

# to both producer and consumer projects, whereas the

4679

# `library.googleapis.com/book/overdue_count` metric is only sent to the

4680

# consumer project.

4681

#

4682

# monitored_resources:

4683

# - type: library.googleapis.com/branch

4684

# labels:

4685

# - key: /city

4686

# description: The city where the library branch is located in.

4687

# - key: /name

4688

# description: The name of the branch.

4689

# metrics:

4690

# - name: library.googleapis.com/book/returned_count

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

4695

# - name: library.googleapis.com/book/overdue_count

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

4700

# monitoring:

4701

# producer_destinations:

4702

# - monitored_resource: library.googleapis.com/branch

4703

# metrics:

4704

# - library.googleapis.com/book/returned_count

4705

# consumer_destinations:

4706

# - monitored_resource: library.googleapis.com/branch

4707

# metrics:

4708

# - library.googleapis.com/book/returned_count

4709

# - library.googleapis.com/book/overdue_count

4710

"producerDestinations": [ # Monitoring configurations for sending metrics to the producer project.

4711

# There can be multiple producer destinations, each one must have a

4712

# different monitored resource type. A metric can be used in at most

4713

# one producer destination.

4714

{ # Configuration of a specific monitoring destination (the producer project

4715

# or the consumer project).

4716

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4717

# Service.monitored_resources section.

4718

"metrics": [ # Names of the metrics to report to this monitoring destination.

4719

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

"consumerDestinations": [ # Monitoring configurations for sending metrics to the consumer project.

4725

# There can be multiple consumer destinations, each one must have a

4726

# different monitored resource type. A metric can be used in at most

4727

# one consumer destination.

4728

{ # Configuration of a specific monitoring destination (the producer project

4729

# or the consumer project).

4730

"monitoredResource": "A String", # The monitored resource type. The type must be defined in

4731

# Service.monitored_resources section.

4732

"metrics": [ # Names of the metrics to report to this monitoring destination.

4733

# Each name must be defined in Service.metrics section.

"A String",

],

},

],

},

"title": "A String", # The product title associated with this service.

4740

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

4741

# by the client for tracking purpose. If empty, the server may choose to

4742

# generate one instead.

4743

"authentication": { # `Authentication` defines the authentication configuration for an API. # Auth configuration.

4744

#

4745

# Example for an API targeted for external use:

4746

#

4747

# name: calendar.googleapis.com

4748

# authentication:

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4749

# providers:

4750

# - id: google_calendar_auth

4751

# jwks_uri: https://www.googleapis.com/oauth2/v1/certs

4752

# issuer: https://securetoken.google.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4753

# rules:

4754

# - selector: "*"

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4755

# requirements:

4756

# provider_id: google_calendar_auth

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4757

"rules": [ # A list of authentication rules that apply to individual API methods.

4758

#

4759

# **NOTE:** All service configuration rules follow "last one wins" order.

4760

{ # Authentication rules for the service.

4761

#

4762

# By default, if a method has any authentication requirements, every request

4763

# must include a valid credential matching one of the requirements.

4764

# It's an error to include more than one kind of credential in a single

4765

# request.

4766

#

4767

# If a method doesn't have any auth requirements, request credentials will be

4768

# ignored.

4769

"oauth": { # OAuth scopes are a way to define data and permissions on data. For example, # The requirements for OAuth credentials.

4770

# there are scopes defined for "Read-only access to Google Calendar" and

4771

# "Access to Cloud Platform". Users can consent to a scope for an application,

4772

# giving it permission to access that data on their behalf.

4773

#

4774

# OAuth scope specifications should be fairly coarse grained; a user will need

4775

# to see and understand the text description of what your scope means.

4776

#

4777

# In most cases: use one or at most two OAuth scopes for an entire family of

4778

# products. If your product has multiple APIs, you should probably be sharing

4779

# the OAuth scope across all of those APIs.

4780

#

4781

# When you need finer grained OAuth consent screens: talk with your product

4782

# management about how developers will use them in practice.

4783

#

4784

# Please note that even though each of the canonical scopes is enough for a

4785

# request to be accepted and passed to the backend, a request can still fail

4786

# due to the backend requiring additional scopes or permissions.

4787

"canonicalScopes": "A String", # The list of publicly documented OAuth scopes that are allowed access. An

4788

# OAuth token containing any of these scopes will be accepted.

#

# Example:

#

# canonical_scopes: https://www.googleapis.com/auth/calendar,

4793

# https://www.googleapis.com/auth/calendar.read

4794

},

4795

"requirements": [ # Requirements for additional authentication providers.

4796

{ # User-defined authentication requirements, including support for

4797

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4798

"providerId": "A String", # id from authentication provider.

#

# Example:

#

# provider_id: bookstore_auth

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4803

"audiences": "A String", # NOTE: This will be deprecated soon, once AuthProvider.audiences is

4804

# implemented and accepted in all the runtime components.

4805

#

4806

# The list of JWT

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4807

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4808

# that are allowed to access. A JWT containing any of these audiences will

4809

# be accepted. When this setting is absent, only JWTs with audience

4810

# "https://Service_name/API_name"

4811

# will be accepted. For example, if no audiences are in the setting,

4812

# LibraryService API will only accept JWTs with the following audience

4813

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4818

# bookstore_web.apps.googleusercontent.com

4819

},

4820

],

Jon Wayne Parrott

2016-08-29 10:21:22 -0700

[diff] [blame]

4821

"allowWithoutCredential": True or False, # Whether to allow requests without a credential. The credential can be

4822

# an OAuth token, Google cookies (first-party auth) or EndUserCreds.

4823

#

4824

# For requests without credentials, if the service control environment is

4825

# specified, each incoming request **must** be associated with a service

4826

# consumer. This can be done by passing an API key that belongs to a consumer

4827

# project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4828

"selector": "A String", # Selects the methods to which this rule applies.

4829

#

4830

# Refer to selector for syntax details.

4831

},

4832

],

4833

"providers": [ # Defines a set of authentication providers that a service supports.

4834

{ # Configuration for an anthentication provider, including support for

4835

# [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).

4836

"jwksUri": "A String", # URL of the provider's public key set to validate signature of the JWT. See

4837

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

4838

# Optional if the key set document:

4839

# - can be retrieved from

4840

# [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html

4841

# of the issuer.

4842

# - can be inferred from the email domain of the issuer (e.g. a Google service account).

4843

#

4844

# Example: https://www.googleapis.com/oauth2/v1/certs

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4845

"audiences": "A String", # The list of JWT

4846

# [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3).

4847

# that are allowed to access. A JWT containing any of these audiences will

4848

# be accepted. When this setting is absent, only JWTs with audience

4849

# "https://Service_name/API_name"

4850

# will be accepted. For example, if no audiences are in the setting,

4851

# LibraryService API will only accept JWTs with the following audience

4852

# "https://library-example.googleapis.com/google.example.library.v1.LibraryService".

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

4857

# bookstore_web.apps.googleusercontent.com

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4858

"id": "A String", # The unique identifier of the auth provider. It will be referred to by

4859

# `AuthRequirement.provider_id`.

4860

#

4861

# Example: "bookstore_auth".

4862

"issuer": "A String", # Identifies the principal that issued the JWT. See

4863

# https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1

4864

# Usually a URL or an email address.

4865

#

4866

# Example: https://securetoken.google.com

4867

# Example: 1234567-compute@developer.gserviceaccount.com

},

],

},

"usage": { # Configuration controlling usage of a service. # Configuration controlling usage of this service.

4872

"rules": [ # A list of usage rules that apply to individual API methods.

4873

#

4874

# **NOTE:** All service configuration rules follow "last one wins" order.

4875

{ # Usage configuration rules for the service.

4876

#

4877

# NOTE: Under development.

4878

#

4879

#

4880

# Use this rule to configure unregistered calls for the service. Unregistered

4881

# calls are calls that do not contain consumer project identity.

4882

# (Example: calls that do not contain an API key).

4883

# By default, API methods do not allow unregistered calls, and each method call

4884

# must be identified by a consumer project identity. Use this rule to

4885

# allow/disallow unregistered calls.

4886

#

4887

# Example of an API that wants to allow unregistered calls for entire service.

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

4893

#

4894

# Example of a method that wants to allow unregistered calls.

#

# usage:

# rules:

# - selector: "google.example.library.v1.LibraryService.CreateBook"

4899

# allow_unregistered_calls: true

4900

"selector": "A String", # Selects the methods to which this rule applies. Use '*' to indicate all

4901

# methods in all APIs.

4902

#

4903

# Refer to selector for syntax details.

4904

"allowUnregisteredCalls": True or False, # True, if the method allows unregistered calls; false otherwise.

4905

},

4906

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4907

"producerNotificationChannel": "A String", # The full resource name of a channel used for sending notifications to the

4908

# service producer.

4909

#

4910

# Google Service Management currently only supports

4911

# [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) as a notification

4912

# channel. To use Google Cloud Pub/Sub as the channel, this must be the name

4913

# of a Cloud Pub/Sub topic that uses the Cloud Pub/Sub topic name format

4914

# documented in https://cloud.google.com/pubsub/docs/overview.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4915

"requirements": [ # Requirements that must be satisfied before a consumer project can use the

4916

# service. Each requirement is of the form <service.name>/<requirement-id>;

4917

# for example 'serviceusage.googleapis.com/billing-enabled'.

"A String",

],

},

"configVersion": 42, # The version of the service configuration. The config version may

4922

# influence interpretation of the configuration, for example, to

4923

# determine defaults. This is documented together with applicable

4924

# options. The current default for the config version itself is `3`.

4925

"producerProjectId": "A String", # The id of the Google developer project that owns the service.

4926

# Members of this project can manage the service configuration,

4927

# manage consumption of the service, etc.

4928

"http": { # Defines the HTTP configuration for a service. It contains a list of # HTTP configuration.

4929

# HttpRule, each specifying the mapping of an RPC method

4930

# to one or more HTTP REST API methods.

4931

"rules": [ # A list of HTTP configuration rules that apply to individual API methods.

4932

#

4933

# **NOTE:** All service configuration rules follow "last one wins" order.

4934

{ # `HttpRule` defines the mapping of an RPC method to one or more HTTP

4935

# REST APIs. The mapping determines what portions of the request

4936

# message are populated from the path, query parameters, or body of

4937

# the HTTP request. The mapping is typically specified as an

4938

# `google.api.http` annotation, see "google/api/annotations.proto"

4939

# for details.

4940

#

4941

# The mapping consists of a field specifying the path template and

4942

# method kind. The path template can refer to fields in the request

4943

# message, as in the example below which describes a REST GET

4944

# operation on a resource collection of messages:

4945

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4946

#

4947

# service Messaging {

4948

# rpc GetMessage(GetMessageRequest) returns (Message) {

4949

# option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}";

4950

# }

4951

# }

4952

# message GetMessageRequest {

4953

# message SubMessage {

4954

# string subfield = 1;

4955

# }

4956

# string message_id = 1; // mapped to the URL

4957

# SubMessage sub = 2; // `sub.subfield` is url-mapped

4958

# }

4959

# message Message {

4960

# string text = 1; // content of the resource

4961

# }

4962

#

4963

# The same http annotation can alternatively be expressed inside the

4964

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

4969

# get: /v1/messages/{message_id}/{sub.subfield}

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4970

#

4971

# This definition enables an automatic, bidrectional mapping of HTTP

4972

# JSON to RPC. Example:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))`

4977

#

4978

# In general, not only fields but also field paths can be referenced

4979

# from a path pattern. Fields mapped to the path pattern cannot be

4980

# repeated and must have a primitive (non-message) type.

4981

#

4982

# Any fields in the request message which are not bound by the path

4983

# pattern automatically become (optional) HTTP query

4984

# parameters. Assume the following definition of the request message:

4985

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

4986

#

4987

# message GetMessageRequest {

4988

# message SubMessage {

4989

# string subfield = 1;

4990

# }

4991

# string message_id = 1; // mapped to the URL

4992

# int64 revision = 2; // becomes a parameter

4993

# SubMessage sub = 3; // `sub.subfield` becomes a parameter

4994

# }

4995

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

4996

#

4997

# 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"))`

5002

#

5003

# Note that fields which are mapped to HTTP parameters must have a

5004

# primitive type or a repeated primitive type. Message types are not

5005

# allowed. In the case of a repeated type, the parameter can be

5006

# repeated in the URL, as in `...?param=A&param=B`.

5007

#

5008

# For HTTP method kinds which allow a request body, the `body` field

5009

# specifies the mapping. Consider a REST update method on the

5010

# message resource collection:

5011

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5012

#

5013

# service Messaging {

5014

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

5015

# option (google.api.http) = {

5016

# put: "/v1/messages/{message_id}"

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

5022

# string message_id = 1; // mapped to the URL

5023

# Message message = 2; // mapped to the body

5024

# }

5025

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5026

#

5027

# The following HTTP JSON to RPC mapping is enabled, where the

5028

# representation of the JSON in the request body is determined by

5029

# protos JSON encoding:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`

5034

#

5035

# The special name `*` can be used in the body mapping to define that

5036

# every field not bound by the path template should be mapped to the

5037

# request body. This enables the following alternative definition of

5038

# the update method:

5039

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5040

# service Messaging {

5041

# rpc UpdateMessage(Message) returns (Message) {

5042

# option (google.api.http) = {

5043

# put: "/v1/messages/{message_id}"

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

5050

# string text = 2;

5051

# }

5052

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5053

#

5054

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

# -----|-----

# `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`

5059

#

5060

# Note that when using `*` in the body mapping, it is not possible to

5061

# have HTTP parameters, as all fields not bound by the path end in

5062

# the body. This makes this option more rarely used in practice of

5063

# defining REST APIs. The common usage of `*` is in custom methods

5064

# which don't use the URL at all for transferring data.

5065

#

5066

# It is possible to define multiple HTTP methods for one RPC by using

5067

# the `additional_bindings` option. Example:

5068

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5069

# service Messaging {

5070

# rpc GetMessage(GetMessageRequest) returns (Message) {

5071

# option (google.api.http) = {

5072

# get: "/v1/messages/{message_id}"

5073

# additional_bindings {

5074

# get: "/v1/users/{user_id}/messages/{message_id}"

5075

# }

5076

# };

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5077

# }

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5078

# }

5079

# message GetMessageRequest {

5080

# string message_id = 1;

5081

# string user_id = 2;

5082

# }

5083

#

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5084

#

5085

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

# -----|-----

# `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`

5091

# `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`

5092

#

5093

# # Rules for HTTP mapping

5094

#

5095

# The rules for mapping HTTP path, query parameters, and body fields

5096

# to the request message are as follows:

5097

#

5098

# 1. The `body` field specifies either `*` or a field path, or is

5099

# omitted. If omitted, it assumes there is no HTTP body.

5100

# 2. Leaf fields (recursive expansion of nested messages in the

5101

# request) can be classified into three types:

5102

# (a) Matched in the URL template.

5103

# (b) Covered by body (if body is `*`, everything except (a) fields;

5104

# else everything under the body field)

5105

# (c) All other fields.

5106

# 3. URL query parameters found in the HTTP request are mapped to (c) fields.

5107

# 4. Any body sent with an HTTP request can contain only (b) fields.

5108

#

5109

# The syntax of the path template is as follows:

5110

#

5111

# Template = "/" Segments [ Verb ] ;

5112

# Segments = Segment { "/" Segment } ;

5113

# Segment = "*" | "**" | LITERAL | Variable ;

5114

# Variable = "{" FieldPath [ "=" Segments ] "}" ;

5115

# FieldPath = IDENT { "." IDENT } ;

5116

# Verb = ":" LITERAL ;

5117

#

5118

# The syntax `*` matches a single path segment. It follows the semantics of

5119

# [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String

5120

# Expansion.

5121

#

5122

# The syntax `**` matches zero or more path segments. It follows the semantics

5123

# of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5124

# Expansion. NOTE: it must be the last segment in the path except the Verb.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5125

#

5126

# The syntax `LITERAL` matches literal text in the URL path.

5127

#

5128

# The syntax `Variable` matches the entire path as specified by its template;

5129

# this nested template must not contain further variables. If a variable

5130

# matches a single path segment, its template may be omitted, e.g. `{var}`

5131

# is equivalent to `{var=*}`.

5132

#

5133

# NOTE: the field paths in variables and in the `body` must not refer to

5134

# repeated fields or map fields.

5135

#

5136

# Use CustomHttpPattern to specify any HTTP method that is not included in the

5137

# `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for

5138

# a given URL path rule. The wild-card rule is useful for services that provide

5139

# content to Web (HTML) clients.

5140

"body": "A String", # The name of the request field whose value is mapped to the HTTP body, or

5141

# `*` for mapping all fields not captured by the path pattern to the HTTP

5142

# body. NOTE: the referred field must not be a repeated field and must be

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5143

# present at the top-level of request message type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5144

"get": "A String", # Used for listing and getting information about resources.

5145

"mediaDownload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

5146

# [][google.bytestream.RestByteStream] as an API to your

5147

# configuration.

5148

# [][google.bytestream.RestByteStream] as an API to your

5149

# configuration.

5150

"enabled": True or False, # Whether download is enabled.

5151

},

5152

"additionalBindings": [ # Additional HTTP bindings for the selector. Nested bindings must

5153

# not contain an `additional_bindings` field themselves (that is,

5154

# the nesting may only be one level deep).

5155

# Object with schema name: HttpRule

5156

],

5157

"mediaUpload": { # Do not use this. For media support, add instead # Do not use this. For media support, add instead

5158

# [][google.bytestream.RestByteStream] as an API to your

5159

# configuration.

5160

# [][google.bytestream.RestByteStream] as an API to your

5161

# configuration.

5162

"enabled": True or False, # Whether upload is enabled.

5163

},

5164

"custom": { # A custom pattern is used for defining custom HTTP verb. # Custom pattern is used for defining custom verbs.

5165

"path": "A String", # The path matched by this custom verb.

5166

"kind": "A String", # The name of this custom HTTP verb.

5167

},

5168

"responseBody": "A String", # The name of the response field whose value is mapped to the HTTP body of

5169

# response. Other response fields are ignored. This field is optional. When

5170

# not set, the response message will be used as HTTP body of response.

5171

# NOTE: the referred field must be not a repeated field and must be present

5172

# at the top-level of response message type.

5173

"put": "A String", # Used for updating a resource.

5174

"patch": "A String", # Used for updating a resource.

5175

"post": "A String", # Used for creating a resource.

5176

"selector": "A String", # Selects methods to which this rule applies.

5177

#

5178

# Refer to selector for syntax details.

5179

"delete": "A String", # Used for deleting a resource.

},

],

},

"apis": [ # A list of API interfaces exported by this service. Only the `name` field

5184

# of the google.protobuf.Api needs to be provided by the configuration

5185

# author, as the remaining fields will be derived from the IDL during the

5186

# normalization process. It is an error to specify an API interface here

5187

# which cannot be resolved against the associated IDL files.

5188

{ # Api is a light-weight descriptor for a protocol buffer service.

5189

"methods": [ # The methods of this api, in unspecified order.

5190

{ # Method represents a method of an api.

5191

"name": "A String", # The simple name of this method.

5192

"requestStreaming": True or False, # If true, the request is streamed.

5193

"responseTypeUrl": "A String", # The URL of the output message type.

5194

"requestTypeUrl": "A String", # A URL of the input message type.

5195

"responseStreaming": True or False, # If true, the response is streamed.

5196

"syntax": "A String", # The source syntax of this method.

5197

"options": [ # Any metadata attached to the method.

5198

{ # A protocol buffer option, which can be attached to a message, field,

5199

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5200

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5201

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5202

# For custom options, it should be the fully-qualified name. For example,

5203

# `"google.api.http"`.

5204

"value": { # The option's value packed in an Any message. If the value is a primitive,

5205

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5206

# should be used. If the value is an enum, it should be stored as an int32

5207

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5208

"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

5215

# message.

5216

# protobuf element, like the file in which it is defined.

5217

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5218

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5219

},

5220

"mixins": [ # Included APIs. See Mixin.

5221

{ # Declares an API to be included in this API. The including API must

5222

# redeclare all the methods from the included API, but documentation

5223

# and options are inherited as follows:

5224

#

5225

# - If after comment and whitespace stripping, the documentation

5226

# string of the redeclared method is empty, it will be inherited

5227

# from the original method.

5228

#

5229

# - Each annotation belonging to the service config (http,

5230

# visibility) which is not set in the redeclared method will be

5231

# inherited.

5232

#

5233

# - If an http annotation is inherited, the path pattern will be

5234

# modified as follows. Any version prefix will be replaced by the

5235

# version of the including API plus the root path if specified.

5236

#

5237

# Example of a simple mixin:

5238

#

5239

# package google.acl.v1;

5240

# service AccessControl {

5241

# // Get the underlying ACL object.

5242

# rpc GetAcl(GetAclRequest) returns (Acl) {

5243

# option (google.api.http).get = "/v1/{resource=**}:getAcl";

# }

# }

#

# package google.storage.v2;

5248

# service Storage {

5249

# // rpc GetAcl(GetAclRequest) returns (Acl);

5250

#

5251

# // Get a data record.

5252

# rpc GetData(GetDataRequest) returns (Data) {

5253

# option (google.api.http).get = "/v2/{resource=**}";

# }

# }

#

# Example of a mixin configuration:

5258

#

5259

# apis:

5260

# - name: google.storage.v2.Storage

5261

# mixins:

5262

# - name: google.acl.v1.AccessControl

5263

#

5264

# The mixin construct implies that all methods in `AccessControl` are

5265

# also declared with same name and request/response types in

5266

# `Storage`. A documentation generator or annotation processor will

5267

# see the effective `Storage.GetAcl` method after inherting

5268

# documentation and annotations as follows:

5269

#

5270

# service Storage {

5271

# // Get the underlying ACL object.

5272

# rpc GetAcl(GetAclRequest) returns (Acl) {

5273

# option (google.api.http).get = "/v2/{resource=**}:getAcl";

# }

# ...

# }

#

# Note how the version in the path pattern changed from `v1` to `v2`.

5279

#

5280

# If the `root` field in the mixin is specified, it should be a

5281

# relative path under which inherited HTTP paths are placed. Example:

5282

#

5283

# apis:

5284

# - name: google.storage.v2.Storage

5285

# mixins:

5286

# - name: google.acl.v1.AccessControl

5287

# root: acls

5288

#

5289

# This implies the following inherited HTTP annotation:

5290

#

5291

# service Storage {

5292

# // Get the underlying ACL object.

5293

# rpc GetAcl(GetAclRequest) returns (Acl) {

5294

# option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

# }

# ...

# }

"root": "A String", # If non-empty specifies a path under which inherited HTTP paths

5299

# are rooted.

5300

"name": "A String", # The fully qualified name of the API which is included.

5301

},

5302

],

5303

"syntax": "A String", # The source syntax of the service.

5304

"version": "A String", # A version string for this api. If specified, must have the form

5305

# `major-version.minor-version`, as in `1.10`. If the minor version

5306

# is omitted, it defaults to zero. If the entire version field is

5307

# empty, the major version is derived from the package name, as

5308

# outlined below. If the field is not empty, the version in the

5309

# package name will be verified to be consistent with what is

5310

# provided here.

5311

#

5312

# The versioning schema uses [semantic

5313

# versioning](http://semver.org) where the major version number

5314

# indicates a breaking change and the minor version an additive,

5315

# non-breaking change. Both version numbers are signals to users

5316

# what to expect from different versions, and should be carefully

5317

# chosen based on the product plan.

5318

#

5319

# The major version is also reflected in the package name of the

5320

# API, which must end in `v<major-version>`, as in

5321

# `google.feature.v1`. For major versions 0 and 1, the suffix can

5322

# be omitted. Zero major versions must only be used for

5323

# experimental, none-GA apis.

5324

"options": [ # Any metadata attached to the API.

5325

{ # A protocol buffer option, which can be attached to a message, field,

5326

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5327

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5328

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5329

# For custom options, it should be the fully-qualified name. For example,

5330

# `"google.api.http"`.

5331

"value": { # The option's value packed in an Any message. If the value is a primitive,

5332

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5333

# should be used. If the value is an enum, it should be stored as an int32

5334

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5335

"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

5340

# followed by the api's simple name.

5341

},

5342

],

5343

"customError": { # Customize service error responses. For example, list any service # Custom error configuration.

5344

# specific protobuf types that can appear in error detail lists of

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

5352

# - google.foo.v1.AnotherError

5353

"rules": [ # The list of custom error rules that apply to individual API messages.

5354

#

5355

# **NOTE:** All service configuration rules follow "last one wins" order.

5356

{ # A custom error rule.

5357

"isErrorType": True or False, # Mark this message as possible payload in error response. Otherwise,

5358

# objects of this type will be filtered when they appear in error payload.

5359

"selector": "A String", # Selects messages to which this rule applies.

5360

#

5361

# Refer to selector for syntax details.

5362

},

5363

],

5364

"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.

5369

# elements. Restrictions are specified using visibility labels

5370

# (e.g., TRUSTED_TESTER) that are elsewhere linked to users and projects.

5371

#

5372

# Users and projects can have access to more than one visibility label. The

5373

# effective visibility for multiple labels is the union of each label's

5374

# elements, plus any unrestricted elements.

5375

#

5376

# If an element and its parents have no restrictions, visibility is

5377

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5384

# restriction: TRUSTED_TESTER

5385

# - selector: google.calendar.Calendar.Delegate

5386

# restriction: GOOGLE_INTERNAL

5387

#

5388

# Here, all methods are publicly visible except for the restricted methods

5389

# EnhancedSearch and Delegate.

5390

"rules": [ # A list of visibility rules that apply to individual API elements.

5391

#

5392

# **NOTE:** All service configuration rules follow "last one wins" order.

5393

{ # A visibility rule provides visibility configuration for an individual API

5394

# element.

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5395

"restriction": "A String", # A comma-separated list of visibility labels that apply to the `selector`.

5396

# Any of the listed labels can be used to grant the visibility.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5397

#

5398

# If a rule has multiple labels, removing one of the labels but not all of

5399

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

5406

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

5407

#

5408

# Removing GOOGLE_INTERNAL from this restriction will break clients that

5409

# rely on this method and only had access to it through GOOGLE_INTERNAL.

5410

"selector": "A String", # Selects methods, messages, fields, enums, etc. to which this rule applies.

5411

#

5412

# Refer to selector for syntax details.

},

],

},

"metrics": [ # Defines the metrics used by this service.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5417

{ # Defines a metric type and its schema. Once a metric descriptor is created,

5418

# deleting or altering it stops data collection and makes the metric type's

5419

# existing data unusable.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5420

"displayName": "A String", # A concise name for the metric, which can be displayed in user interfaces.

5421

# Use sentence case without an ending period, for example "Request count".

5422

"description": "A String", # A detailed description of the metric, which can be used in documentation.

5423

"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]

5424

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5425

"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]

5426

# Some combinations of `metric_kind` and `value_type` might not be supported.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5427

"labels": [ # The set of labels that can be used to describe a specific

5428

# instance of this metric type. For example, the

5429

# `appengine.googleapis.com/http/server/response_latencies` metric

5430

# type has a label for the HTTP response code, `response_code`, so

5431

# you can look at latencies for successful responses or just

5432

# for responses that failed.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5433

{ # A description of a label.

5434

"valueType": "A String", # The type of data that can be assigned to the label.

5435

"description": "A String", # A human-readable description for the label.

5436

"key": "A String", # The label key.

5437

},

5438

],

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5439

"type": "A String", # The metric type, including its DNS name prefix. The type is not

5440

# URL-encoded. All user-defined metric types have the DNS name

5441

# `custom.googleapis.com`. Metric types should use a natural hierarchical

5442

# grouping. For example:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5443

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5444

# "custom.googleapis.com/invoice/paid/amount"

5445

# "appengine.googleapis.com/http/server/response_latencies"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5446

"unit": "A String", # The unit in which the metric value is reported. It is only applicable

5447

# if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The

5448

# supported units are a subset of [The Unified Code for Units of

5449

# Measure](http://unitsofmeasure.org/ucum.html) standard:

5450

#

5451

# **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)

5466

# * `P` peta (10**15)

5467

# * `E` exa (10**18)

5468

# * `Z` zetta (10**21)

5469

# * `Y` yotta (10**24)

5470

# * `m` milli (10**-3)

5471

# * `u` micro (10**-6)

5472

# * `n` nano (10**-9)

5473

# * `p` pico (10**-12)

5474

# * `f` femto (10**-15)

5475

# * `a` atto (10**-18)

5476

# * `z` zepto (10**-21)

5477

# * `y` yocto (10**-24)

5478

# * `Ki` kibi (2**10)

5479

# * `Mi` mebi (2**20)

5480

# * `Gi` gibi (2**30)

5481

# * `Ti` tebi (2**40)

#

# **Grammar**

#

# The grammar includes the dimensionless unit `1`, such as `1/s`.

5486

#

5487

# The grammar also includes these connectors:

5488

#

5489

# * `/` division (as an infix operator, e.g. `1/s`).

5490

# * `.` multiplication (as an infix operator, e.g. `GBy.d`)

5491

#

5492

# The grammar for a unit is as follows:

5493

#

5494

# Expression = Component { "." Component } { "/" Component } ;

5495

#

5496

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

# * `Annotation` is just a comment if it follows a `UNIT` and is

5506

# equivalent to `1` if it is used alone. For examples,

5507

# `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.

5508

# * `NAME` is a sequence of non-blank printable ASCII characters not

5509

# containing '{' or '}'.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5510

"name": "A String", # The resource name of the metric descriptor. Depending on the

5511

# implementation, the name typically includes: (1) the parent resource name

5512

# that defines the scope of the metric type or of its data; and (2) the

5513

# metric's URL-encoded type, which also appears in the `type` field of this

5514

# descriptor. For example, following is the resource name of a custom

5515

# metric within the GCP project 123456789:

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5516

#

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5517

# "projects/123456789/metricDescriptors/custom.googleapis.com%2Finvoice%2Fpaid%2Famount"

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5518

},

5519

],

5520

"enums": [ # A list of all enum types included in this API service. Enums

5521

# referenced directly or indirectly by the `apis` are automatically

5522

# included. Enums which are not referenced but shall be included

5523

# should be listed here by name. Example:

5524

#

5525

# enums:

5526

# - name: google.someapi.v1.SomeEnum

5527

{ # Enum type definition.

5528

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5529

# protobuf element, like the file in which it is defined.

5530

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5531

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5532

},

5533

"enumvalue": [ # Enum value definitions.

5534

{ # Enum value definition.

5535

"number": 42, # Enum value number.

5536

"options": [ # Protocol buffer options.

5537

{ # A protocol buffer option, which can be attached to a message, field,

5538

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5539

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5540

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5541

# For custom options, it should be the fully-qualified name. For example,

5542

# `"google.api.http"`.

5543

"value": { # The option's value packed in an Any message. If the value is a primitive,

5544

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5545

# should be used. If the value is an enum, it should be stored as an int32

5546

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5547

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum value name.

5552

},

5553

],

5554

"options": [ # Protocol buffer options.

5555

{ # A protocol buffer option, which can be attached to a message, field,

5556

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5557

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5558

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5559

# For custom options, it should be the fully-qualified name. For example,

5560

# `"google.api.http"`.

5561

"value": { # The option's value packed in an Any message. If the value is a primitive,

5562

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5563

# should be used. If the value is an enum, it should be stored as an int32

5564

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5565

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"name": "A String", # Enum type name.

5570

"syntax": "A String", # The source syntax.

5571

},

5572

],

5573

"types": [ # A list of all proto message types included in this API service.

5574

# Types referenced directly or indirectly by the `apis` are

5575

# automatically included. Messages which are not referenced but

5576

# shall be included, such as types used by the `google.protobuf.Any` type,

5577

# should be listed here by name. Example:

5578

#

5579

# types:

5580

# - name: google.protobuf.Int32

5581

{ # A protocol buffer message type.

5582

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5583

"A String",

5584

],

5585

"name": "A String", # The fully qualified message name.

5586

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5587

# protobuf element, like the file in which it is defined.

5588

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5589

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5590

},

5591

"syntax": "A String", # The source syntax.

5592

"fields": [ # The list of fields.

5593

{ # A single field of a message type.

5594

"kind": "A String", # The field type.

5595

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5596

# types. The first type has index 1; zero means the type is not in the list.

5597

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5598

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5599

"name": "A String", # The field name.

5600

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5601

"jsonName": "A String", # The field JSON name.

5602

"number": 42, # The field number.

5603

"cardinality": "A String", # The field cardinality.

5604

"options": [ # The protocol buffer options.

5605

{ # A protocol buffer option, which can be attached to a message, field,

5606

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5607

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5608

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5609

# For custom options, it should be the fully-qualified name. For example,

5610

# `"google.api.http"`.

5611

"value": { # The option's value packed in an Any message. If the value is a primitive,

5612

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5613

# should be used. If the value is an enum, it should be stored as an int32

5614

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5615

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5620

},

5621

],

5622

"options": [ # The protocol buffer options.

5623

{ # A protocol buffer option, which can be attached to a message, field,

5624

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5625

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5626

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5627

# For custom options, it should be the fully-qualified name. For example,

5628

# `"google.api.http"`.

5629

"value": { # The option's value packed in an Any message. If the value is a primitive,

5630

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5631

# should be used. If the value is an enum, it should be stored as an int32

5632

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5633

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

},

],

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5639

"logging": { # Logging configuration of the service. # Logging configuration.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5640

#

5641

# The following example shows how to configure logs to be sent to the

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5642

# producer and consumer projects. In the example, the `activity_history`

5643

# log is sent to both the producer and consumer projects, whereas the

5644

# `purchase_history` log is only sent to the producer project.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5645

#

5646

# monitored_resources:

5647

# - type: library.googleapis.com/branch

5648

# labels:

5649

# - key: /city

5650

# description: The city where the library branch is located in.

5651

# - key: /name

5652

# description: The name of the branch.

5653

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5654

# - name: activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5655

# labels:

5656

# - key: /customer_id

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5657

# - name: purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5658

# logging:

5659

# producer_destinations:

5660

# - monitored_resource: library.googleapis.com/branch

5661

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5662

# - activity_history

5663

# - purchase_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5664

# consumer_destinations:

5665

# - monitored_resource: library.googleapis.com/branch

5666

# logs:

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5667

# - activity_history

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5668

"producerDestinations": [ # Logging configurations for sending logs to the producer project.

5669

# There can be multiple producer destinations, each one must have a

5670

# different monitored resource type. A log can be used in at most

5671

# one producer destination.

5672

{ # Configuration of a specific logging destination (the producer project

5673

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5674

"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]

5675

# Service.monitored_resources section.

5676

"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]

5677

# be defined in the Service.logs section. If the log name is

5678

# not a domain scoped name, it will be automatically prefixed with

5679

# 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.

5685

# There can be multiple consumer destinations, each one must have a

5686

# different monitored resource type. A log can be used in at most

5687

# one consumer destination.

5688

{ # Configuration of a specific logging destination (the producer project

5689

# or the consumer project).

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

5690

"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]

5691

# Service.monitored_resources section.

5692

"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]

5693

# be defined in the Service.logs section. If the log name is

5694

# not a domain scoped name, it will be automatically prefixed with

5695

# 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,

5702

# e.g. `calendar.googleapis.com`.

5703

"documentation": { # `Documentation` provides the information for describing a service. # Additional API documentation.

5704

#

5705

# Example:

5706

# <pre><code>documentation:

5707

# summary: >

5708

# The Google Calendar API gives access

5709

# to most calendar features.

5710

# pages:

5711

# - name: Overview

5712

# content: (== include google/foo/overview.md ==)

5713

# - name: Tutorial

5714

# content: (== include google/foo/tutorial.md ==)

5715

# subpages;

5716

# - name: Java

5717

# content: (== include google/foo/tutorial_java.md ==)

5718

# rules:

5719

# - selector: google.calendar.Calendar.Get

5720

# description: >

5721

# ...

5722

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

5727

# standard markdown features, definition lists, tables and fenced

5728

# code blocks are supported. Section headers can be provided and are

5729

# interpreted relative to the section nesting of the context where

5730

# a documentation fragment is embedded.

5731

#

5732

# Documentation from the IDL is merged with documentation defined

5733

# via the config at normalization time, where documentation provided

5734

# by config rules overrides IDL provided.

5735

#

5736

# A number of constructs specific to the API platform are supported

5737

# in documentation text.

5738

#

5739

# In order to reference a proto element, the following

5740

# notation can be used:

5741

# <pre><code>[fully.qualified.proto.name][]</code></pre>

5742

# To override the display text used for the link, this can be used:

5743

# <pre><code>[display text][fully.qualified.proto.name]</code></pre>

5744

# Text can be excluded from doc using the following notation:

5745

# <pre><code>(-- internal comment --)</code></pre>

5746

# Comments can be made conditional using a visibility label. The below

5747

# text will be only rendered if the `BETA` label is available:

5748

# <pre><code>(--BETA: comment for BETA users --)</code></pre>

5749

# A few directives are available in documentation. Note that

5750

# directives must appear on a single line to be properly

5751

# identified. The `include` directive includes a markdown file from

5752

# an external source:

5753

# <pre><code>(== include path/to/file ==)</code></pre>

5754

# The `resource_for` directive marks a message to be the resource of

5755

# a collection in REST view. If it is not specified, tools attempt

5756

# to infer the resource from the operations in a collection:

5757

# <pre><code>(== resource_for v1.shelves.books ==)</code></pre>

5758

# The directive `suppress_warning` does not directly affect documentation

5759

# and is documented together with service config validation.

5760

"rules": [ # A list of documentation rules that apply to individual API elements.

5761

#

5762

# **NOTE:** All service configuration rules follow "last one wins" order.

5763

{ # A documentation rule provides information about individual API elements.

5764

"description": "A String", # Description of the selected API(s).

5765

"deprecationDescription": "A String", # Deprecation description of the selected element(s). It can be provided if an

5766

# element is marked as `deprecated`.

5767

"selector": "A String", # The selector is a comma-separated list of patterns. Each pattern is a

5768

# qualified name of the element which may end in "*", indicating a wildcard.

5769

# Wildcards are only allowed at the end and for a whole component of the

5770

# qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To

5771

# specify a default for all applicable elements, the whole pattern "*"

# is used.

},

],

"overview": "A String", # Declares a single overview page. For example:

5776

# <pre><code>documentation:

5777

# summary: ...

5778

# overview: (== include overview.md ==)

5779

# </code></pre>

5780

# This is a shortcut for the following declaration (using pages style):

5781

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

# content: (== include overview.md ==)

5786

# </code></pre>

5787

# Note: you cannot specify both `overview` field and `pages` field.

5788

"summary": "A String", # A short summary of what the service does. Can only be provided by

5789

# plain text.

5790

"pages": [ # The top level pages for the documentation set.

5791

{ # Represents a documentation page. A page can contain subpages to represent

5792

# nested documentation set structure.

5793

"content": "A String", # The Markdown content of the page. You can use <code>(== include {path} ==)</code>

5794

# to include content from a Markdown file.

5795

"subpages": [ # Subpages of this page. The order of subpages specified here will be

5796

# honored in the generated docset.

5797

# Object with schema name: Page

5798

],

5799

"name": "A String", # The name of the page. It will be used as an identity of the page to

5800

# generate URI of the page, text of the link to this page in navigation,

5801

# etc. The full page name (start from the root page name to this page

5802

# concatenated with `.`) can be used as reference to the page in your

5803

# documentation. For example:

5804

# <pre><code>pages:

5805

# - name: Tutorial

5806

# content: (== include tutorial.md ==)

5807

# subpages:

5808

# - name: Java

5809

# content: (== include tutorial_java.md ==)

5810

# </code></pre>

5811

# You can reference `Java` page using Markdown reference link syntax:

# `Java`.

},

],

"documentationRootUrl": "A String", # The URL to the root of documentation.

5816

},

5817

"systemTypes": [ # A list of all proto message types included in this API service.

5818

# It serves similar purpose as [google.api.Service.types], except that

5819

# these types are not needed by user-defined APIs. Therefore, they will not

5820

# show up in the generated discovery doc. This field should only be used

5821

# to define system APIs in ESF.

5822

{ # A protocol buffer message type.

5823

"oneofs": [ # The list of types appearing in `oneof` definitions in this type.

5824

"A String",

5825

],

5826

"name": "A String", # The fully qualified message name.

5827

"sourceContext": { # `SourceContext` represents information about the source of a # The source context.

5828

# protobuf element, like the file in which it is defined.

5829

"fileName": "A String", # The path-qualified name of the .proto file that contained the associated

5830

# protobuf element. For example: `"google/protobuf/source_context.proto"`.

5831

},

5832

"syntax": "A String", # The source syntax.

5833

"fields": [ # The list of fields.

5834

{ # A single field of a message type.

5835

"kind": "A String", # The field type.

5836

"oneofIndex": 42, # The index of the field type in `Type.oneofs`, for message or enumeration

5837

# types. The first type has index 1; zero means the type is not in the list.

5838

"typeUrl": "A String", # The field type URL, without the scheme, for message or enumeration

5839

# types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

5840

"name": "A String", # The field name.

5841

"defaultValue": "A String", # The string value of the default value of this field. Proto2 syntax only.

5842

"jsonName": "A String", # The field JSON name.

5843

"number": 42, # The field number.

5844

"cardinality": "A String", # The field cardinality.

5845

"options": [ # The protocol buffer options.

5846

{ # A protocol buffer option, which can be attached to a message, field,

5847

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5848

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5849

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5850

# For custom options, it should be the fully-qualified name. For example,

5851

# `"google.api.http"`.

5852

"value": { # The option's value packed in an Any message. If the value is a primitive,

5853

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5854

# should be used. If the value is an enum, it should be stored as an int32

5855

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5856

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

},

],

"packed": True or False, # Whether to use alternative packed wire representation.

5861

},

5862

],

5863

"options": [ # The protocol buffer options.

5864

{ # A protocol buffer option, which can be attached to a message, field,

5865

# enumeration, etc.

Jon Wayne Parrott

2017-01-06 09:58:29 -0800

[diff] [blame^]

5866

"name": "A String", # The option's name. For protobuf built-in options (options defined in

5867

# descriptor.proto), this is the short name. For example, `"map_entry"`.

5868

# For custom options, it should be the fully-qualified name. For example,

5869

# `"google.api.http"`.

5870

"value": { # The option's value packed in an Any message. If the value is a primitive,

5871

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

5872

# should be used. If the value is an enum, it should be stored as an int32

5873

# value using the google.protobuf.Int32Value type.

Jon Wayne Parrott

2016-08-16 12:44:29 -0700

[diff] [blame]

5874

"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

5889

# - google.rpc.context.OriginContext

5890

#

5891

# The above specifies that all methods in the API request

5892

# `google.rpc.context.ProjectContext` and

5893

# `google.rpc.context.OriginContext`.

5894

#

5895

# Available context types are defined in package

5896

# `google.rpc.context`.

5897

"rules": [ # A list of RPC context rules that apply to individual API methods.

5898

#

5899

# **NOTE:** All service configuration rules follow "last one wins" order.

5900

{ # A context rule provides information about the context for an individual API

5901

# element.

5902

"provided": [ # A list of full type names of provided contexts.

5903

"A String",

5904

],

5905

"requested": [ # A list of full type names of requested contexts.

5906

"A String",

5907

],

5908

"selector": "A String", # Selects the methods to which this rule applies.

5909

#

5910

# Refer to selector for syntax details.

5911

},

5912

],

5913

},

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5914

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

5915

# with the same name as the service is automatically generated to service all

5916

# defined APIs.

5917

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

5918

# A service may expose any number of endpoints, and all endpoints share the

5919

# same service configuration, such as quota configuration and monitoring

5920

# configuration.

5921

#

5922

# Example service configuration:

5923

#

5924

# name: library-example.googleapis.com

5925

# endpoints:

5926

# # Below entry makes 'google.example.library.v1.Library'

5927

# # API be served from endpoint address library-example.googleapis.com.

5928

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

5929

# # it to decide whether the subsequent cross-origin request is

5930

# # allowed to proceed.

5931

# - name: library-example.googleapis.com

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5932

# allow_cors: true

Sai Cheemalapati

2016-10-12 14:05:53 -0700

[diff] [blame]

5933

"allowCors": True or False, # Allowing

5934

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

5935

# cross-domain traffic, would allow the backends served from this endpoint to

5936

# receive and respond to HTTP OPTIONS requests. The response will be used by

5937

# the browser to determine whether the subsequent cross-origin request is

5938

# allowed to proceed.

5939

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

5940

# please specify multiple google.api.Endpoint for each of the intented

5941

# alias.

5942

#

5943

# Additional names that this endpoint will be hosted on.

5944

"A String",

5945

],

5946

"features": [ # The list of features enabled on this endpoint.

5947

"A String",

5948

],

5949

"name": "A String", # The canonical name of this endpoint.

5950

"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>

5962

<pre>Retrieves the next page of results.

5963

5964

Args:

5965

previous_request: The request for the previous page. (required)

5966

previous_response: The response from the request for the previous page. (required)

5967

5968

Returns:

5969

A request object that you can call 'execute()' on to request the next

5970

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>

5976

<pre>Creates a new service configuration (version) for a managed service based

5977

on

5978

user-supplied configuration source files (for example: OpenAPI

5979

Specification). This method stores the source configurations as well as the

5980

generated service configuration. To rollout the service configuration to

5981

other services,

5982

please call CreateServiceRollout.

5983

5984

Operation<response: SubmitConfigSourceResponse>

5985

5986

Args:

5987

serviceName: string, The name of the service. See the [overview](/service-management/overview)

5988

for naming requirements. For example: `example.googleapis.com`. (required)

5989

body: object, The request body. (required)

5990

The object takes the form of:

5991

5992

{ # Request message for SubmitConfigSource method.

5993

"validateOnly": True or False, # Optional. If set, this will result in the generation of a

5994

# `google.api.Service` configuration based on the `ConfigSource` provided,

5995

# but the generated config and the sources will NOT be persisted.

5996

"configSource": { # Represents a source file which is used to generate the service configuration # The source configuration for the service.

5997

# defined by `google.api.Service`.

5998

"files": [ # Set of source configuration files that are used to generate a service

5999

# configuration (`google.api.Service`).

6000

{ # Generic specification of a source configuration file

6001

"fileContents": "A String", # The bytes that constitute the file.

6002

"fileType": "A String", # The type of configuration file this represents.

6003

"filePath": "A String", # The file name of the configuration file (full or relative path).

6004

},

6005

],

6006

"id": "A String", # A unique ID for a specific instance of this message, typically assigned

6007

# by the client for tracking purpose. If empty, the server may choose to

6008

# 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:

6019

6020

{ # This resource represents a long-running operation that is the result of a

6021

# network API call.

6022

"metadata": { # Service-specific metadata associated with the operation. It typically

6023

# contains progress information and common metadata such as create time.

6024

# Some services might not provide such metadata. Any method that returns a

6025

# long-running operation should document the metadata type, if any.

6026

"a_key": "", # Properties of the object. Contains field @type with type URL.

6027

},

6028

"done": True or False, # If the value is `false`, it means the operation is still in progress.

6029

# If true, the operation is completed, and either `error` or `response` is

6030

# available.

6031

"response": { # The normal response of the operation in case of success. If the original

6032

# method returns no data on success, such as `Delete`, the response is

6033

# `google.protobuf.Empty`. If the original method is standard

6034

# `Get`/`Create`/`Update`, the response should be the resource. For other

6035

# methods, the response should have the type `XxxResponse`, where `Xxx`

6036

# is the original method name. For example, if the original method name

6037

# is `TakeSnapshot()`, the inferred response type is

6038

# `TakeSnapshotResponse`.

6039

"a_key": "", # Properties of the object. Contains field @type with type URL.

6040

},

6041

"name": "A String", # The server-assigned name, which is only unique within the same service that

6042

# originally returns it. If you use the default HTTP mapping, the

6043

# `name` should have the format of `operations/some/unique/name`.

Sai Cheemalapati

2016-10-21 13:59:49 -0700

[diff] [blame]

6044

"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