Blame - docs/dyn/serviceuser_v1.projects.services.html - platform/external/python/google-api-python-client

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

[diff] [blame]

78

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

Sai Cheemalapati

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

[diff] [blame]

79

<p class="firstline">Disable a service so it can no longer be used with a</p>

80

Thomas Coffee

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

[diff] [blame]

81

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

Sai Cheemalapati

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

[diff] [blame]

82

<p class="firstline">Enable a service so it can be used with a project.</p>

83

Sai Cheemalapati

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

[diff] [blame]

84

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

Sai Cheemalapati

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

[diff] [blame]

85

<p class="firstline">List enabled services for the specified consumer.</p>

86

87

<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>

88

<p class="firstline">Retrieves the next page of results.</p>

89

<h3>Method Details</h3>

90

Thomas Coffee

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

[diff] [blame]

91

<code class="details" id="disable">disable(name, body, x__xgafv=None)</code>

Sai Cheemalapati

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

[diff] [blame]

92

<pre>Disable a service so it can no longer be used with a

93

project. This prevents unintended usage that may cause unexpected billing

94

charges or security leaks.

95

96

Operation<response: google.protobuf.Empty>

97

98

Args:

99

name: string, Name of the consumer and the service to disable for that consumer.

100

101

The Service User implementation accepts the following forms for consumer:

102

- "project:<project_id>"

103

104

A valid path would be:

105

- /v1/projects/my-project/services/servicemanagement.googleapis.com:disable (required)

106

body: object, The request body. (required)

107

The object takes the form of:

108

109

{ # Request message for DisableService method.

110

}

111

112

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

119

120

{ # This resource represents a long-running operation that is the result of a

121

# network API call.

Sai Cheemalapati

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

[diff] [blame]

122

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

123

# programming environments, including REST APIs and RPC APIs. It is used by

124

# [gRPC](https://github.com/grpc). The error model is designed to be:

125

#

126

# - Simple to use and understand for most users

127

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

132

# and error details. The error code should be an enum value of

133

# google.rpc.Code, but it may accept additional error codes if needed. The

134

# error message should be a developer-facing English message that helps

135

# developers *understand* and *resolve* the error. If a localized user-facing

136

# error message is needed, put the localized message in the error details or

137

# localize it in the client. The optional error details may contain arbitrary

138

# information about the error. There is a predefined set of error detail types

Sai Cheemalapati

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

[diff] [blame]

139

# in the package `google.rpc` that can be used for common error conditions.

Sai Cheemalapati

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

[diff] [blame]

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

144

# is not necessarily the actual wire format. When the `Status` message is

145

# exposed in different client libraries and different wire protocols, it can be

146

# mapped differently. For example, it will likely be mapped to some exceptions

147

# in Java, but more likely mapped to some error codes in C.

#

# # Other uses

#

# The error model and the `Status` message can be used in a variety of

152

# environments, either with or without APIs, to provide a

153

# consistent developer experience across different environments.

154

#

155

# Example uses of this error model include:

156

#

157

# - Partial errors. If a service needs to return partial errors to the client,

158

# it may embed the `Status` in the normal response to indicate the partial

159

# errors.

160

#

161

# - Workflow errors. A typical workflow has multiple steps. Each step may

Sai Cheemalapati

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

[diff] [blame]

162

# have a `Status` message for error reporting.

Sai Cheemalapati

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

[diff] [blame]

163

#

164

# - Batch operations. If a client uses batch request and batch response, the

165

# `Status` message should be used directly inside batch response, one for

166

# each error sub-response.

167

#

168

# - Asynchronous operations. If an API call embeds asynchronous operation

169

# results in its response, the status of those operations should be

170

# represented directly using the `Status` message.

171

#

172

# - Logging. If some API errors are stored in logs, the message `Status` could

173

# be used directly after any stripping needed for security/privacy reasons.

174

"message": "A String", # A developer-facing error message, which should be in English. Any

175

# user-facing error message should be localized and sent in the

176

# google.rpc.Status.details field, or localized by the client.

177

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

178

"details": [ # A list of messages that carry the error details. There will be a

179

# common set of message types for APIs to use.

180

{

181

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

},

],

},

"done": True or False, # If the value is `false`, it means the operation is still in progress.

186

# If true, the operation is completed, and either `error` or `response` is

187

# available.

188

"response": { # The normal response of the operation in case of success. If the original

189

# method returns no data on success, such as `Delete`, the response is

190

# `google.protobuf.Empty`. If the original method is standard

191

# `Get`/`Create`/`Update`, the response should be the resource. For other

192

# methods, the response should have the type `XxxResponse`, where `Xxx`

193

# is the original method name. For example, if the original method name

194

# is `TakeSnapshot()`, the inferred response type is

195

# `TakeSnapshotResponse`.

196

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

197

},

198

"name": "A String", # The server-assigned name, which is only unique within the same service that

199

# originally returns it. If you use the default HTTP mapping, the

200

# `name` should have the format of `operations/some/unique/name`.

Sai Cheemalapati

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

[diff] [blame]

201

"metadata": { # Service-specific metadata associated with the operation. It typically

202

# contains progress information and common metadata such as create time.

203

# Some services might not provide such metadata. Any method that returns a

204

# long-running operation should document the metadata type, if any.

205

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

206

},

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

Thomas Coffee

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

[diff] [blame]

211

<code class="details" id="enable">enable(name, body, x__xgafv=None)</code>

Sai Cheemalapati

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

[diff] [blame]

212

<pre>Enable a service so it can be used with a project.

213

See [Cloud Auth Guide](https://cloud.google.com/docs/authentication) for

214

more information.

215

216

Operation<response: google.protobuf.Empty>

217

218

Args:

219

name: string, Name of the consumer and the service to enable for that consumer.

220

221

A valid path would be:

222

- /v1/projects/my-project/services/servicemanagement.googleapis.com:enable (required)

223

body: object, The request body. (required)

224

The object takes the form of:

225

226

{ # Request message for EnableService method.

227

}

228

229

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

236

237

{ # This resource represents a long-running operation that is the result of a

238

# network API call.

Sai Cheemalapati

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

[diff] [blame]

239

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

240

# programming environments, including REST APIs and RPC APIs. It is used by

241

# [gRPC](https://github.com/grpc). The error model is designed to be:

242

#

243

# - Simple to use and understand for most users

244

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

249

# and error details. The error code should be an enum value of

250

# google.rpc.Code, but it may accept additional error codes if needed. The

251

# error message should be a developer-facing English message that helps

252

# developers *understand* and *resolve* the error. If a localized user-facing

253

# error message is needed, put the localized message in the error details or

254

# localize it in the client. The optional error details may contain arbitrary

255

# information about the error. There is a predefined set of error detail types

Sai Cheemalapati

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

[diff] [blame]

256

# in the package `google.rpc` that can be used for common error conditions.

Sai Cheemalapati

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

[diff] [blame]

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

261

# is not necessarily the actual wire format. When the `Status` message is

262

# exposed in different client libraries and different wire protocols, it can be

263

# mapped differently. For example, it will likely be mapped to some exceptions

264

# in Java, but more likely mapped to some error codes in C.

#

# # Other uses

#

# The error model and the `Status` message can be used in a variety of

269

# environments, either with or without APIs, to provide a

270

# consistent developer experience across different environments.

271

#

272

# Example uses of this error model include:

273

#

274

# - Partial errors. If a service needs to return partial errors to the client,

275

# it may embed the `Status` in the normal response to indicate the partial

276

# errors.

277

#

278

# - Workflow errors. A typical workflow has multiple steps. Each step may

Sai Cheemalapati

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

[diff] [blame]

279

# have a `Status` message for error reporting.

Sai Cheemalapati

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

[diff] [blame]

280

#

281

# - Batch operations. If a client uses batch request and batch response, the

282

# `Status` message should be used directly inside batch response, one for

283

# each error sub-response.

284

#

285

# - Asynchronous operations. If an API call embeds asynchronous operation

286

# results in its response, the status of those operations should be

287

# represented directly using the `Status` message.

288

#

289

# - Logging. If some API errors are stored in logs, the message `Status` could

290

# be used directly after any stripping needed for security/privacy reasons.

291

"message": "A String", # A developer-facing error message, which should be in English. Any

292

# user-facing error message should be localized and sent in the

293

# google.rpc.Status.details field, or localized by the client.

294

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

295

"details": [ # A list of messages that carry the error details. There will be a

296

# common set of message types for APIs to use.

297

{

298

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

},

],

},

"done": True or False, # If the value is `false`, it means the operation is still in progress.

303

# If true, the operation is completed, and either `error` or `response` is

304

# available.

305

"response": { # The normal response of the operation in case of success. If the original

306

# method returns no data on success, such as `Delete`, the response is

307

# `google.protobuf.Empty`. If the original method is standard

308

# `Get`/`Create`/`Update`, the response should be the resource. For other

309

# methods, the response should have the type `XxxResponse`, where `Xxx`

310

# is the original method name. For example, if the original method name

311

# is `TakeSnapshot()`, the inferred response type is

312

# `TakeSnapshotResponse`.

313

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

314

},

315

"name": "A String", # The server-assigned name, which is only unique within the same service that

316

# originally returns it. If you use the default HTTP mapping, the

317

# `name` should have the format of `operations/some/unique/name`.

Sai Cheemalapati

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

[diff] [blame]

318

"metadata": { # Service-specific metadata associated with the operation. It typically

319

# contains progress information and common metadata such as create time.

320

# Some services might not provide such metadata. Any method that returns a

321

# long-running operation should document the metadata type, if any.

322

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

323

},

Sai Cheemalapati

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

[diff] [blame]

}</pre>

</div>

Sai Cheemalapati

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

[diff] [blame]

328

<code class="details" id="list">list(parent, pageToken=None, x__xgafv=None, pageSize=None)</code>

Sai Cheemalapati

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

[diff] [blame]

329

<pre>List enabled services for the specified consumer.

330

331

Args:

332

parent: string, List enabled services for the specified parent.

333

334

An example valid parent would be:

335

- projects/my-project (required)

Sai Cheemalapati

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

[diff] [blame]

336

pageToken: string, Token identifying which result to start with; returned by a previous list

337

call.

338

x__xgafv: string, V1 error format.

339

Allowed values

340

1 - v1 error format

341

2 - v2 error format

Sai Cheemalapati

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

[diff] [blame]

342

pageSize: integer, Requested size of the next page of data.

Sai Cheemalapati

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

[diff] [blame]

343

344

Returns:

345

An object of the form:

346

347

{ # Response message for `ListEnabledServices` method.

348

"services": [ # Services enabled for the specified parent.

349

{ # The published version of a Service that is managed by

350

# Google Service Management.

351

"name": "A String", # The resource name of the service.

352

#

353

# A valid name would be:

354

# - services/serviceuser.googleapis.com

355

"service": { # `Service` is the root object of Google service configuration schema. It # The service's published configuration.

356

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

357

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

358

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

359

# specific aspect, such as auth. See each proto message definition for details.

#

# Example:

#

# type: google.api.Service

364

# config_version: 3

365

# name: calendar.googleapis.com

366

# title: Google Calendar API

367

# apis:

368

# - name: google.calendar.v3.Calendar

369

# authentication:

370

# providers:

371

# - id: google_calendar_auth

372

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

373

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

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

378

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

379

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

380

# monitoring, etc.

381

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

382

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

383

},

384

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

385

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

386

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

387

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

388

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

389

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

390

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

391

#

392

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

393

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

394

# by the API.

Thomas Coffee

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

[diff] [blame]

395

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

396

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

397

# The maximum length of this value is 256 characters.

Sai Cheemalapati

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

[diff] [blame]

398

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

399

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

400

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

401

{ # A description of a label.

402

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

403

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

404

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

405

},

406

],

Thomas Coffee

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

[diff] [blame]

407

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

408

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

409

# without any article or other determiners. For example,

410

# `"Google Cloud SQL Database"`.

Sai Cheemalapati

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

[diff] [blame]

411

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

412

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

413

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

414

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

415

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

416

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

417

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

418

# be used in documentation.

419

},

420

],

421

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

422

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

423

#

424

# - name: library.googleapis.com/activity_history

425

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

426

# display_name: Activity

427

# labels:

428

# - key: /customer_id

429

# description: Identifier of a library customer

430

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

431

# Runtime requests that contain labels not specified here are

432

# considered invalid.

433

{ # A description of a label.

434

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

435

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

436

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

437

},

438

],

439

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

440

# the user interface and should be concise.

441

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

442

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

443

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

444

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

445

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

446

# the documentation and can contain details.

447

},

448

],

Sai Cheemalapati

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

[diff] [blame]

449

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

450

#

451

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

452

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

453

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

454

# change the names of the system parameters.

455

"rules": [ # Define system parameters.

456

#

457

# The parameters defined here will override the default parameters

458

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

459

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

460

# and names is implementation-dependent.

461

#

462

# Example: define api key for all methods

#

# system_parameters

# rules:

# - selector: "*"

# parameters:

# - name: api_key

# url_query_parameter: api_key

470

#

471

#

472

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

#

# system_parameters

# rules:

# - selector: "/ListShelves"

477

# parameters:

478

# - name: api_key

479

# http_header: Api-Key1

480

# - name: api_key

481

# http_header: Api-Key2

482

#

483

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

484

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

485

# methods.

486

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

487

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

488

# names are used the behavior is implementation-dependent.

489

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

490

# parameter-dependent.

491

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

492

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

493

# is implementation-dependent.

494

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

495

# sensitive.

496

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

497

# insensitive.

Sai Cheemalapati

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

[diff] [blame]

498

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

Sai Cheemalapati

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

[diff] [blame]

499

},

500

],

501

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

502

# methods in all APIs.

503

#

504

# Refer to selector for syntax details.

505

},

506

],

507

},

Sai Cheemalapati

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

[diff] [blame]

508

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

509

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

510

# generate one instead.

511

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

512

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

513

#

514

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

515

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

516

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

517

#

518

# Refer to selector for syntax details.

Sai Cheemalapati

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

[diff] [blame]

519

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

520

# value lower than this will be rejected.

Sai Cheemalapati

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

[diff] [blame]

521

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

522

# default depends on the deployment context.

523

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

},

],

},

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

528

#

529

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

530

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

531

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

532

# to both producer and consumer projects, whereas the

533

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

534

# consumer project.

535

#

536

# monitored_resources:

537

# - type: library.googleapis.com/branch

538

# labels:

539

# - key: /city

540

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

541

# - key: /name

542

# description: The name of the branch.

543

# metrics:

544

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

# metric_kind: DELTA

# value_type: INT64

# labels:

# - key: /customer_id

549

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

# metric_kind: GAUGE

# value_type: INT64

# labels:

# - key: /customer_id

554

# monitoring:

555

# producer_destinations:

556

# - monitored_resource: library.googleapis.com/branch

557

# metrics:

558

# - library.googleapis.com/book/returned_count

559

# consumer_destinations:

560

# - monitored_resource: library.googleapis.com/branch

561

# metrics:

562

# - library.googleapis.com/book/returned_count

563

# - library.googleapis.com/book/overdue_count

564

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

565

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

566

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

567

# one producer destination.

568

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

569

# or the consumer project).

570

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

571

# Service.monitored_resources section.

572

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

573

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

"A String",

],

},

],

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

579

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

580

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

581

# one consumer destination.

582

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

583

# or the consumer project).

584

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

585

# Service.monitored_resources section.

586

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

587

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

"A String",

],

},

],

},

Sai Cheemalapati

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

[diff] [blame]

593

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

Sai Cheemalapati

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

[diff] [blame]

594

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

595

#

596

# Example for an API targeted for external use:

597

#

598

# name: calendar.googleapis.com

599

# authentication:

600

# providers:

601

# - id: google_calendar_auth

602

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

603

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

# rules:

# - selector: "*"

# requirements:

# provider_id: google_calendar_auth

608

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

609

#

610

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

611

{ # Authentication rules for the service.

612

#

613

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

614

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

615

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

616

# request.

617

#

618

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

619

# ignored.

620

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

621

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

622

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

623

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

624

#

625

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

626

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

627

#

628

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

629

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

630

# the OAuth scope across all of those APIs.

631

#

632

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

633

# management about how developers will use them in practice.

634

#

635

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

636

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

637

# due to the backend requiring additional scopes or permissions.

638

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

639

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

#

# Example:

#

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

644

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

645

},

Sai Cheemalapati

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

[diff] [blame]

646

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

647

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

648

#

649

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

650

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

651

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

652

# project.

Sai Cheemalapati

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

[diff] [blame]

653

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

654

{ # User-defined authentication requirements, including support for

655

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

656

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

#

# Example:

#

# provider_id: bookstore_auth

661

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

662

# implemented and accepted in all the runtime components.

663

#

664

# The list of JWT

665

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

666

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

667

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

668

# "https://Service_name/API_name"

669

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

670

# LibraryService API will only accept JWTs with the following audience

671

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

676

# bookstore_web.apps.googleusercontent.com

677

},

678

],

Sai Cheemalapati

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

[diff] [blame]

679

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

680

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

681

# authentication provider, typically formatted as a SmartService string

682

# (go/smartservice).

683

},

Sai Cheemalapati

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

[diff] [blame]

684

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

685

#

686

# Refer to selector for syntax details.

687

},

688

],

689

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

690

{ # Configuration for an anthentication provider, including support for

691

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

692

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

693

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

694

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

695

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

696

# "https://Service_name/API_name"

697

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

698

# LibraryService API will only accept JWTs with the following audience

699

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

#

# Example:

#

# audiences: bookstore_android.apps.googleusercontent.com,

704

# bookstore_web.apps.googleusercontent.com

705

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

706

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

707

# Optional if the key set document:

708

# - can be retrieved from

709

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

710

# of the issuer.

711

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

712

#

713

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

714

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

715

# `AuthRequirement.provider_id`.

716

#

717

# Example: "bookstore_auth".

718

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

719

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

720

# Usually a URL or an email address.

721

#

722

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

723

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

},

],

},

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

728

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

729

#

730

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

731

{ # Usage configuration rules for the service.

732

#

733

# NOTE: Under development.

734

#

735

#

736

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

737

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

738

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

739

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

740

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

741

# allow/disallow unregistered calls.

742

#

743

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

#

# usage:

# rules:

# - selector: "*"

# allow_unregistered_calls: true

749

#

750

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

#

# usage:

# rules:

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

755

# allow_unregistered_calls: true

756

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

757

# methods in all APIs.

758

#

759

# Refer to selector for syntax details.

760

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

761

},

762

],

763

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

764

# service producer.

765

#

766

# Google Service Management currently only supports

767

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

768

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

769

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

770

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

771

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

772

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

773

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

"A String",

],

},

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

778

# influence interpretation of the configuration, for example, to

779

# determine defaults. This is documented together with applicable

780

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

781

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

782

# Members of this project can manage the service configuration,

783

# manage consumption of the service, etc.

784

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

785

# HttpRule, each specifying the mapping of an RPC method

786

# to one or more HTTP REST API methods.

787

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

788

#

789

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

790

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

791

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

792

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

793

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

794

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

795

# for details.

796

#

797

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

798

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

799

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

800

# operation on a resource collection of messages:

801

#

802

#

803

# service Messaging {

804

# rpc GetMessage(GetMessageRequest) returns (Message) {

805

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

806

# }

807

# }

808

# message GetMessageRequest {

809

# message SubMessage {

810

# string subfield = 1;

811

# }

812

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

813

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

814

# }

815

# message Message {

816

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

817

# }

818

#

819

# The same http annotation can alternatively be expressed inside the

820

# `GRPC API Configuration` YAML file.

#

# http:

# rules:

# - selector: <proto_package_name>.Messaging.GetMessage

825

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

826

#

827

# This definition enables an automatic, bidrectional mapping of HTTP

828

# JSON to RPC. Example:

#

# HTTP | RPC

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

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

833

#

834

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

835

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

836

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

837

#

838

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

839

# pattern automatically become (optional) HTTP query

840

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

841

#

842

#

Sai Cheemalapati

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

[diff] [blame]

843

# service Messaging {

844

# rpc GetMessage(GetMessageRequest) returns (Message) {

845

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

846

# }

847

# }

Sai Cheemalapati

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

[diff] [blame]

848

# message GetMessageRequest {

849

# message SubMessage {

850

# string subfield = 1;

851

# }

852

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

853

# int64 revision = 2; // becomes a parameter

854

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

# }

#

#

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

#

# HTTP | RPC

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

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

863

#

864

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

865

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

866

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

867

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

868

#

869

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

870

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

871

# message resource collection:

872

#

873

#

874

# service Messaging {

875

# rpc UpdateMessage(UpdateMessageRequest) returns (Message) {

876

# option (google.api.http) = {

877

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

# body: "message"

# };

# }

# }

# message UpdateMessageRequest {

883

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

884

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

# }

#

#

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

889

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

890

# protos JSON encoding:

#

# HTTP | RPC

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

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

895

#

896

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

897

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

898

# request body. This enables the following alternative definition of

899

# the update method:

900

#

901

# service Messaging {

902

# rpc UpdateMessage(Message) returns (Message) {

903

# option (google.api.http) = {

904

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

# body: "*"

# };

# }

# }

# message Message {

# string message_id = 1;

# string text = 2;

# }

#

#

# The following HTTP JSON to RPC mapping is enabled:

#

# HTTP | RPC

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

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

920

#

921

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

922

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

923

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

924

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

925

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

926

#

927

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

928

# the `additional_bindings` option. Example:

929

#

930

# service Messaging {

931

# rpc GetMessage(GetMessageRequest) returns (Message) {

932

# option (google.api.http) = {

933

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

934

# additional_bindings {

935

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

# }

# };

# }

# }

# message GetMessageRequest {

941

# string message_id = 1;

942

# string user_id = 2;

# }

#

#

# This enables the following two alternative HTTP JSON to RPC

# mappings:

#

# HTTP | RPC

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

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

952

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

953

#

954

# # Rules for HTTP mapping

955

#

956

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

957

# to the request message are as follows:

958

#

959

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

960

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

961

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

962

# request) can be classified into three types:

963

# (a) Matched in the URL template.

964

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

965

# else everything under the body field)

966

# (c) All other fields.

967

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

968

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

969

#

970

# The syntax of the path template is as follows:

971

#

972

# Template = "/" Segments [ Verb ] ;

973

# Segments = Segment { "/" Segment } ;

974

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

975

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

976

# FieldPath = IDENT { "." IDENT } ;

977

# Verb = ":" LITERAL ;

978

#

979

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

980

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

981

# Expansion.

982

#

983

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

984

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

985

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

986

#

987

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

988

#

989

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

990

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

991

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

992

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

993

#

994

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

995

# repeated fields or map fields.

996

#

997

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

998

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

999

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

1000

# content to Web (HTML) clients.

1001

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

1002

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

1003

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

1004

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

Sai Cheemalapati

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

[diff] [blame]

1005

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

Sai Cheemalapati

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

[diff] [blame]

1006

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

1007

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

1008

# Example:

1009

#

1010

# rpc AddressesAggregatedList(AddressesAggregatedListRequest)

1011

# returns (AddressesAggregatedListResponse) {

1012

# option (google.api.http) = {

1013

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

1014

# rest_collection: "projects.addresses"

# };

# }

#

# This method has the automatically derived collection name

1019

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

1020

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

1021

# field is configured to override the derived collection name.

Sai Cheemalapati

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

[diff] [blame]

1022

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

1023

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

1024

# the nesting may only be one level deep).

1025

# Object with schema name: HttpRule

1026

],

Sai Cheemalapati

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

[diff] [blame]

1027

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

Sai Cheemalapati

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

[diff] [blame]

1028

# Bytestream, add instead

1029

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

1030

# configuration for Bytestream methods.

Sai Cheemalapati

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

[diff] [blame]

1031

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

Sai Cheemalapati

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

[diff] [blame]

1032

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

1033

# your configuration for Bytestream methods.

Sai Cheemalapati

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

[diff] [blame]

1034

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

1035

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

1036

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

1037

# of the given patterns.

1038

"A String",

1039

],

Sai Cheemalapati

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

[diff] [blame]

1040

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

Sai Cheemalapati

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

[diff] [blame]

1041

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

1042

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

1043

# by the client and will not consume quota.

1044

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

1045

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

1046

# The size is specified in bytes.

1047

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

Sai Cheemalapati

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

[diff] [blame]

1048

#

1049

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

1050

},

Sai Cheemalapati

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

[diff] [blame]

1051

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

1052

#

1053

# Refer to selector for syntax details.

Sai Cheemalapati

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

[diff] [blame]

1054

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

1055

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

1056

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

1057

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

1058

# at the top-level of response message type.

Sai Cheemalapati

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

[diff] [blame]

1059

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

1060

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

1061

# Example:

1062

#

1063

# rpc CreateResource(CreateResourceRequest)

1064

# returns (CreateResourceResponse) {

1065

# option (google.api.http) = {

1066

# post: "/v1/resources",

1067

# body: "resource",

1068

# rest_method_name: "insert"

# };

# }

#

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

1073

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

1074

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

1075

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

1076

# API to your configuration.

1077

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

1078

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

1079

# your configuration for Bytestream methods.

1080

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

1081

# download of this media.

1082

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

1083

# download should be sent to the backend.

1084

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

1085

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

1086

# The size is specified in bytes.

1087

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

1088

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

1089

#

1090

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

1091

},

Sai Cheemalapati

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

[diff] [blame]

1092

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

Sai Cheemalapati

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

[diff] [blame]

1093

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

Sai Cheemalapati

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

[diff] [blame]

1094

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

1095

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

1096

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

1097

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

1098

},

1099

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

1100

},

1101

],

Sai Cheemalapati

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

[diff] [blame]

1102

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

1103

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

1104

# left encoded.

1105

#

1106

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

1107

# segment matches.

Sai Cheemalapati

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

[diff] [blame]

1108

},

1109

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

1110

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

1111

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

1112

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

1113

# which cannot be resolved against the associated IDL files.

1114

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

Sai Cheemalapati

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

[diff] [blame]

1115

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

1116

# followed by the api's simple name.

Sai Cheemalapati

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

[diff] [blame]

1117

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

1118

# message.

1119

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

1120

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

1121

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

1122

},

1123

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

1124

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

1125

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

1126

# and options are inherited as follows:

1127

#

1128

# - If after comment and whitespace stripping, the documentation

1129

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

1130

# from the original method.

1131

#

1132

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

1133

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

1134

# inherited.

1135

#

1136

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

1137

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

1138

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

1139

#

1140

# Example of a simple mixin:

1141

#

1142

# package google.acl.v1;

1143

# service AccessControl {

1144

# // Get the underlying ACL object.

1145

# rpc GetAcl(GetAclRequest) returns (Acl) {

1146

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

# }

# }

#

# package google.storage.v2;

1151

# service Storage {

1152

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

1153

#

1154

# // Get a data record.

1155

# rpc GetData(GetDataRequest) returns (Data) {

1156

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

# }

# }

#

# Example of a mixin configuration:

1161

#

1162

# apis:

1163

# - name: google.storage.v2.Storage

1164

# mixins:

1165

# - name: google.acl.v1.AccessControl

1166

#

1167

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

1168

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

1169

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

1170

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

1171

# documentation and annotations as follows:

1172

#

1173

# service Storage {

1174

# // Get the underlying ACL object.

1175

# rpc GetAcl(GetAclRequest) returns (Acl) {

1176

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

# }

# ...

# }

#

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

1182

#

1183

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

1184

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

1185

#

1186

# apis:

1187

# - name: google.storage.v2.Storage

1188

# mixins:

1189

# - name: google.acl.v1.AccessControl

1190

# root: acls

1191

#

1192

# This implies the following inherited HTTP annotation:

1193

#

1194

# service Storage {

1195

# // Get the underlying ACL object.

1196

# rpc GetAcl(GetAclRequest) returns (Acl) {

1197

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

# }

# ...

# }

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

1202

# are rooted.

1203

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

1204

},

1205

],

1206

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

1207

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

1208

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

1209

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

1210

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

1211

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

1212

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

1213

# provided here.

1214

#

1215

# The versioning schema uses [semantic

1216

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

1217

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

1218

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

1219

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

1220

# chosen based on the product plan.

1221

#

1222

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

1223

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

1224

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

1225

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

1226

# experimental, none-GA apis.

1227

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

1228

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

1229

# enumeration, etc.

1230

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

1231

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

1232

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

1233

# `"google.api.http"`.

1234

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

1235

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

1236

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

1237

# value using the google.protobuf.Int32Value type.

1238

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

1239

},

1240

},

1241

],

Sai Cheemalapati

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

[diff] [blame]

1242

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

1243

{ # Method represents a method of an api.

1244

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

1245

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

1246

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

1247

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

1248

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

1249

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

1250

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

1251

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

1252

# enumeration, etc.

1253

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

1254

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

1255

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

1256

# `"google.api.http"`.

1257

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

1258

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

1259

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

1260

# value using the google.protobuf.Int32Value type.

1261

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1267

},

1268

],

1269

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

1270

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

# error responses.

#

# Example:

#

# custom_error:

# types:

# - google.foo.v1.CustomError

1278

# - google.foo.v1.AnotherError

1279

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

1280

#

1281

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

1282

{ # A custom error rule.

1283

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

1284

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

1285

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

1286

#

1287

# Refer to selector for syntax details.

1288

},

1289

],

1290

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

1291

"A String",

1292

],

1293

},

Sai Cheemalapati

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

[diff] [blame]

1294

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

1295

# usage.

1296

#

1297

# The quota configuration works this way:

1298

# - The service configuration defines a set of metrics.

1299

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

1300

# corresponding costs.

1301

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

1302

# quota checks at runtime.

1303

#

1304

# An example quota configuration in yaml format:

#

# quota:

#

# - name: apiWriteQpsPerProject

1309

# metric: library.googleapis.com/write_calls

1310

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

# values:

# STANDARD: 10000

#

#

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

1316

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

1317

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

1318

# # consuming at twice rate as the DeleteBook method.

# metric_rules:

# - selector: "*"

# metric_costs:

# library.googleapis.com/read_calls: 1

1323

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

1324

# metric_costs:

1325

# library.googleapis.com/write_calls: 2

1326

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

1327

# metric_costs:

1328

# library.googleapis.com/write_calls: 1

1329

#

1330

# Corresponding Metric definition:

1331

#

1332

# metrics:

1333

# - name: library.googleapis.com/read_calls

1334

# display_name: Read requests

# metric_kind: DELTA

# value_type: INT64

#

# - name: library.googleapis.com/write_calls

1339

# display_name: Write requests

1340

# metric_kind: DELTA

1341

# value_type: INT64

1342

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

1343

# or more metrics.

1344

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

1345

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

1346

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

1347

# cost applied to each metric.

1348

#

1349

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

1350

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

1351

# The value must not be negative.

1352

"a_key": "A String",

1353

},

1354

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

1355

#

1356

# Refer to selector for syntax details.

1357

},

1358

],

1359

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

1360

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

1361

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

1362

# type combination defined within a `QuotaGroup`.

1363

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

1364

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

1365

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

1366

# display name generated from the configuration.

1367

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

1368

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

1369

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

1370

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

1371

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

1372

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

1373

#

1374

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

1375

# are provisioning quota to selected consumers and blocking others.

1376

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

1377

# negative values are allowed.

1378

#

1379

# Used by group-based quotas only.

1380

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

1381

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

1382

# defined within the service config.

1383

#

1384

# Used by metric-based quotas only.

1385

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

1386

"a_key": "A String",

1387

},

1388

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

1389

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

1390

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

1391

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

1392

#

1393

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

1394

# indicating unlimited maximum quota.

1395

#

1396

# Used by group-based quotas only.

1397

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

1398

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

1399

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

1400

# the future. "0" indicates indefinite duration.

1401

#

1402

# Used by group-based quotas only.

1403

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

1404

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

1405

# billed amount when billing is enabled.

1406

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

1407

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

1408

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

1409

#

1410

# Used by group-based quotas only.

1411

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

1412

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

1413

# backend system.

1414

#

1415

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

1416

# supports the following unit components:

1417

# * One of the time intevals:

1418

# * "/min" for quota every minute.

1419

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

1420

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

1421

# * One and only one of the granted containers:

1422

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

1423

#

1424

# Here are some examples:

1425

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

1426

#

1427

# Note: the order of unit components is insignificant.

1428

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

1429

#

1430

# Used by metric-based quotas only.

1431

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

1432

# overriding the default limit on per-consumer basis.

1433

#

1434

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

1435

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

1436

# characters as well as '-'.

1437

#

1438

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

1439

#

1440

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

1441

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

1442

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

1443

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

1444

# affecting the identity of the limit.

1445

},

1446

],

1447

},

Sai Cheemalapati

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

[diff] [blame]

1448

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

1449

# elements. Restrictions are specified using visibility labels

1450

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

1451

#

1452

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

1453

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

1454

# elements, plus any unrestricted elements.

1455

#

1456

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

1457

# unconditionally granted.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1464

# restriction: TRUSTED_TESTER

1465

# - selector: google.calendar.Calendar.Delegate

1466

# restriction: GOOGLE_INTERNAL

1467

#

1468

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

1469

# EnhancedSearch and Delegate.

1470

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

1471

#

1472

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

1473

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

1474

# element.

1475

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

1476

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

1477

#

1478

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

1479

# them can break clients.

#

# Example:

#

# visibility:

# rules:

# - selector: google.calendar.Calendar.EnhancedSearch

1486

# restriction: GOOGLE_INTERNAL, TRUSTED_TESTER

1487

#

1488

# Removing GOOGLE_INTERNAL from this restriction will break clients that

1489

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

1490

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

1491

#

1492

# Refer to selector for syntax details.

},

],

},

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

1497

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

1498

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

1499

# existing data unusable.

1500

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

1501

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

Thomas Coffee

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

[diff] [blame]

1502

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

1503

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

1504

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

1505

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

1506

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

1507

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

1508

#

1509

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

Sai Cheemalapati

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

[diff] [blame]

1510

"metricKind": "A String", # Whether the metric records instantaneous values, changes to a value, etc.

1511

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

1512

"valueType": "A String", # Whether the measurement is an integer, a floating-point number, etc.

1513

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

1514

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

1515

# instance of this metric type. For example, the

1516

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

1517

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

1518

# you can look at latencies for successful responses or just

1519

# for responses that failed.

1520

{ # A description of a label.

1521

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

1522

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

1523

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

1524

},

1525

],

1526

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

1527

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

1528

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

1529

# grouping. For example:

1530

#

1531

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

1532

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

1533

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

1534

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

1535

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

1536

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

1537

#

1538

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

1553

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

1554

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

1555

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

1556

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

1557

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

1558

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

1559

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

1560

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

1561

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

1562

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

1563

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

1564

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

1565

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

1566

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

1567

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

1568

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

#

# **Grammar**

#

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

1573

#

1574

# The grammar also includes these connectors:

1575

#

1576

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

1577

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

1578

#

1579

# The grammar for a unit is as follows:

1580

#

1581

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

1582

#

1583

# Component = [ PREFIX ] UNIT [ Annotation ]

# | Annotation

# | "1"

# ;

#

# Annotation = "{" NAME "}" ;

#

# Notes:

#

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

1593

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

1594

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

1595

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

1596

# containing '{' or '}'.

Thomas Coffee

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

[diff] [blame]

1597

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

Sai Cheemalapati

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

[diff] [blame]

1598

},

1599

],

1600

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

1601

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

1602

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

1603

# should be listed here by name. Example:

1604

#

1605

# enums:

1606

# - name: google.someapi.v1.SomeEnum

1607

{ # Enum type definition.

Sai Cheemalapati

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

[diff] [blame]

1608

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

Sai Cheemalapati

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

[diff] [blame]

1609

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

1610

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

1611

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

1612

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

1613

},

Sai Cheemalapati

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

[diff] [blame]

1614

"options": [ # Protocol buffer options.

1615

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

1616

# enumeration, etc.

1617

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

1618

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

1619

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

1620

# `"google.api.http"`.

1621

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

1622

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

1623

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

1624

# value using the google.protobuf.Int32Value type.

1625

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

},

},

],

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

Sai Cheemalapati

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

[diff] [blame]

1630

"enumvalue": [ # Enum value definitions.

1631

{ # Enum value definition.

Sai Cheemalapati

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

[diff] [blame]

1632

"number": 42, # Enum value number.

1633

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

Sai Cheemalapati

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

[diff] [blame]

1634

"options": [ # Protocol buffer options.

1635

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

1636

# enumeration, etc.

1637

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

1638

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

1639

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

1640

# `"google.api.http"`.

1641

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

1642

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

1643

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

1644

# value using the google.protobuf.Int32Value type.

1645

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

},

},

],

},

],

Sai Cheemalapati

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

[diff] [blame]

1651

},

1652

],

1653

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

1654

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

1655

# automatically included. Messages which are not referenced but

1656

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

1657

# should be listed here by name. Example:

1658

#

1659

# types:

1660

# - name: google.protobuf.Int32

1661

{ # A protocol buffer message type.

1662

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

1663

"A String",

1664

],

1665

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

Sai Cheemalapati

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

[diff] [blame]

1666

"fields": [ # The list of fields.

1667

{ # A single field of a message type.

1668

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

1669

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

1670

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

1671

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

1672

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

1673

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

1674

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

1675

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

1676

"number": 42, # The field number.

1677

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

1678

"options": [ # The protocol buffer options.

1679

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

1680

# enumeration, etc.

1681

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

1682

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

1683

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

1684

# `"google.api.http"`.

1685

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

1686

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

1687

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

1688

# value using the google.protobuf.Int32Value type.

1689

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

},

},

],

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

1694

},

1695

],

Thomas Coffee

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

[diff] [blame]

1696

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

1697

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

1698

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

1699

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

1700

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

1701

},

Sai Cheemalapati

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

[diff] [blame]

1702

"options": [ # The protocol buffer options.

1703

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

1704

# enumeration, etc.

1705

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

1706

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

1707

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

1708

# `"google.api.http"`.

1709

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

1710

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

1711

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

1712

# value using the google.protobuf.Int32Value type.

1713

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

},

},

],

},

],

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

1720

#

1721

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

1722

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

1723

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

1724

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

1725

#

1726

# monitored_resources:

1727

# - type: library.googleapis.com/branch

1728

# labels:

1729

# - key: /city

1730

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

1731

# - key: /name

1732

# description: The name of the branch.

1733

# logs:

1734

# - name: activity_history

1735

# labels:

1736

# - key: /customer_id

1737

# - name: purchase_history

1738

# logging:

1739

# producer_destinations:

1740

# - monitored_resource: library.googleapis.com/branch

# logs:

# - activity_history

# - purchase_history

# consumer_destinations:

1745

# - monitored_resource: library.googleapis.com/branch

1746

# logs:

1747

# - activity_history

1748

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

1749

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

1750

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

1751

# one producer destination.

1752

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

1753

# or the consumer project).

1754

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

1755

# Service.monitored_resources section.

1756

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

1757

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

1758

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

1759

# the service name followed by "/".

"A String",

],

},

],

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

1765

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

1766

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

1767

# one consumer destination.

1768

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

1769

# or the consumer project).

1770

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

1771

# Service.monitored_resources section.

1772

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

1773

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

1774

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

1775

# the service name followed by "/".

"A String",

],

},

],

},

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

1782

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

1783

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

1784

#

1785

# Example:

1786

# <pre><code>documentation:

1787

# summary: >

1788

# The Google Calendar API gives access

1789

# to most calendar features.

1790

# pages:

1791

# - name: Overview

1792

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

1793

# - name: Tutorial

1794

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

1795

# subpages;

1796

# - name: Java

1797

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

1798

# rules:

1799

# - selector: google.calendar.Calendar.Get

1800

# description: >

1801

# ...

1802

# - selector: google.calendar.Calendar.Put

# description: >

# ...

# </code></pre>

# Documentation is provided in markdown syntax. In addition to

1807

# standard markdown features, definition lists, tables and fenced

1808

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

1809

# interpreted relative to the section nesting of the context where

1810

# a documentation fragment is embedded.

1811

#

1812

# Documentation from the IDL is merged with documentation defined

1813

# via the config at normalization time, where documentation provided

1814

# by config rules overrides IDL provided.

1815

#

1816

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

1817

# in documentation text.

1818

#

1819

# In order to reference a proto element, the following

1820

# notation can be used:

1821

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

1822

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

1823

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

1824

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

1825

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

1826

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

1827

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

1828

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

1829

# A few directives are available in documentation. Note that

1830

# directives must appear on a single line to be properly

1831

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

1832

# an external source:

1833

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

1834

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

1835

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

1836

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

1837

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

1838

# The directive `suppress_warning` does not directly affect documentation

1839

# and is documented together with service config validation.

1840

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

1841

#

1842

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

1843

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

1844

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

1845

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

1846

# element is marked as `deprecated`.

1847

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

1848

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

1849

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

1850

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

1851

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

# is used.

},

],

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

1856

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

1857

# <pre><code>documentation:

1858

# summary: ...

1859

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

1860

# </code></pre>

1861

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

1862

# <pre><code>documentation:

# summary: ...

# pages:

# - name: Overview

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

1867

# </code></pre>

1868

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

1869

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

1870

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

1871

# nested documentation set structure.

1872

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

1873

# to include content from a Markdown file.

1874

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

1875

# honored in the generated docset.

1876

# Object with schema name: Page

1877

],

1878

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

1879

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

1880

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

1881

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

1882

# documentation. For example:

1883

# <pre><code>pages:

1884

# - name: Tutorial

1885

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

1886

# subpages:

1887

# - name: Java

1888

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

1889

# </code></pre>

1890

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

# `Java`.

},

],

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

1895

# plain text.

1896

},

1897

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

1898

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

1899

{

1900

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

},

],

},

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

1905

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

1906

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

1907

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

1908

# to define system APIs in ESF.

1909

{ # A protocol buffer message type.

1910

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

1911

"A String",

1912

],

1913

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

Sai Cheemalapati

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

[diff] [blame]

1914

"fields": [ # The list of fields.

1915

{ # A single field of a message type.

1916

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

1917

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

1918

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

1919

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

1920

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

1921

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

1922

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

1923

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

1924

"number": 42, # The field number.

1925

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

1926

"options": [ # The protocol buffer options.

1927

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

1928

# enumeration, etc.

1929

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

1930

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

1931

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

1932

# `"google.api.http"`.

1933

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

1934

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

1935

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

1936

# value using the google.protobuf.Int32Value type.

1937

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

},

},

],

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

1942

},

1943

],

Thomas Coffee

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

[diff] [blame]

1944

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

1945

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

1946

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

1947

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

1948

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

1949

},

Sai Cheemalapati

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

[diff] [blame]

1950

"options": [ # The protocol buffer options.

1951

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

1952

# enumeration, etc.

1953

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

1954

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

1955

# For custom options, it should be the fully-qualified name. For example,

1956

# `"google.api.http"`.

1957

"value": { # The option's value packed in an Any message. If the value is a primitive,

1958

# the corresponding wrapper type defined in google/protobuf/wrappers.proto

1959

# should be used. If the value is an enum, it should be stored as an int32

1960

# value using the google.protobuf.Int32Value type.

1961

"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

1976

# - google.rpc.context.OriginContext

1977

#

1978

# The above specifies that all methods in the API request

1979

# `google.rpc.context.ProjectContext` and

1980

# `google.rpc.context.OriginContext`.

1981

#

1982

# Available context types are defined in package

1983

# `google.rpc.context`.

1984

"rules": [ # A list of RPC context rules that apply to individual API methods.

1985

#

1986

# **NOTE:** All service configuration rules follow "last one wins" order.

1987

{ # A context rule provides information about the context for an individual API

1988

# element.

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1989

"provided": [ # A list of full type names of provided contexts.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1990

"A String",

1991

],

Sai Cheemalapati

2017-03-24 15:06:46 -0700

[diff] [blame]

1992

"requested": [ # A list of full type names of requested contexts.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1993

"A String",

1994

],

1995

"selector": "A String", # Selects the methods to which this rule applies.

1996

#

1997

# Refer to selector for syntax details.

1998

},

1999

],

2000

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2001

"endpoints": [ # Configuration for network endpoints. If this is empty, then an endpoint

2002

# with the same name as the service is automatically generated to service all

2003

# defined APIs.

2004

{ # `Endpoint` describes a network endpoint that serves a set of APIs.

2005

# A service may expose any number of endpoints, and all endpoints share the

2006

# same service configuration, such as quota configuration and monitoring

2007

# configuration.

2008

#

2009

# Example service configuration:

2010

#

2011

# name: library-example.googleapis.com

2012

# endpoints:

2013

# # Below entry makes 'google.example.library.v1.Library'

2014

# # API be served from endpoint address library-example.googleapis.com.

2015

# # It also allows HTTP OPTIONS calls to be passed to the backend, for

2016

# # it to decide whether the subsequent cross-origin request is

2017

# # allowed to proceed.

2018

# - name: library-example.googleapis.com

2019

# allow_cors: true

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2020

"features": [ # The list of features enabled on this endpoint.

2021

"A String",

2022

],

2023

"apis": [ # The list of APIs served by this endpoint.

2024

#

2025

# If no APIs are specified this translates to "all APIs" exported by the

2026

# service, as defined in the top-level service configuration.

2027

"A String",

2028

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2029

"allowCors": True or False, # Allowing

2030

# [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), aka

2031

# cross-domain traffic, would allow the backends served from this endpoint to

2032

# receive and respond to HTTP OPTIONS requests. The response will be used by

2033

# the browser to determine whether the subsequent cross-origin request is

2034

# allowed to proceed.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

2035

"name": "A String", # The canonical name of this endpoint.

2036

"target": "A String", # The specification of an Internet routable address of API frontend that will

2037

# handle requests to this [API Endpoint](https://cloud.google.com/apis/design/glossary).

2038

# It should be either a valid IPv4 address or a fully-qualified domain name.

2039

# For example, "8.8.8.8" or "myservice.appspot.com".

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

2040

"aliases": [ # DEPRECATED: This field is no longer supported. Instead of using aliases,

2041

# please specify multiple google.api.Endpoint for each of the intented

2042

# alias.

2043

#

2044

# Additional names that this endpoint will be hosted on.

2045

"A String",

2046

],

Sai Cheemalapati